この記事では、Intercom開発環境のセットアップ、SSL付きのカスタムHelp Centerドメインの設定、アクセス・トークンやOAuthによるアプリ認証、Intercom APIを使った連絡先、会話、ticketsの管理方法を説明します。また、webhook、ページネーション、MessengerおよびInboxアプリの構築、一般的なAPIおよびSSLエラーのトラブルシューティングも扱います。Intercomとの統合を構築する開発者向けです。

アプリ開発用に新しいdeveloper workspaceを作成できます。developer workspaceは無料で、開発目的専用です。作成後はこのガイドに従い、アプリを作成し最初のAPIコールを行えます。

本番workspace用に新しいアプリを作成し、アクセス・トークンを取得するには、https://app.intercom.com/a/apps/{your-workspace-id}/developer-hub/にアクセスしてください。

Articles Help Centerを有効にすると、コンテンツはデフォルトでintercom.help経由で利用可能になります。URLはintercom.help/exampleappのようになります。

別のURLを使いたい場合は、カスタムドメインを手動で設定して作成できます。Help Center設定でカスタムドメインを入力し、カスタムCNAMEレコードを作成し、必要に応じてSSLを設定します。設定手順はdeveloper documentationにあります。 カスタムドメイン設定後にHelp Centerで「not found」エラーが出る場合は、CNAMEレコードが正しいIntercomホストを指しているか確認してください： • HTTPS Quick Setupの場合：us.intercomhelpcenter.com（米国リージョン） • 手動/HTTP設定の場合：custom.intercom.help（米国リージョン） また、Help Center設定のセキュリティプロトコルがDNS設定と一致しているかも確認してください。

SSL（またはTLS）は、サーバーとブラウザ間の接続を安全に暗号化する最も一般的な方法です。接続は暗号化され安全で、HTTPSとして表示されます。

カスタムドメインのArticlesでSSLを設定する方法は2つあります。

はい！Help Center設定で「HTTPS（quick setup）」を有効にすると、Intercomがカスタムドメイン（例：https://help.ourdomain.com）のSSL証明書を自動的に発行・管理します。手動でのSSL設定は不要で、CNAMEをus.intercomhelpcenter.comに向けるだけで残りはIntercomが対応します。

カスタムドメインをHTTPSに切り替えたい場合：

カスタムドメインのSSLを設定して機密情報を暗号化できます。これを行う場合は、CloudflareのようなSSL対応のDNSプロバイダーでCNAMEを設定してください。

SSL設定についてはdeveloper documentationのガイドに従ってください。プロバイダーによって設定手順が異なる場合があります。

標準のSSLおよびHTTPS設定で問題が解決しない場合、カスタムHelp Centerドメインの一般的な例外ケースを以下に示します。

1. ドメインが安全でない

ERR_SSL_VERSION_OR_CIPHER_MISMATCH エラー

2. HTTPS設定が保留のまま進まない

3. HTTPS（クイックセットアップ）オプションが利用できない

4. アクセス拒否エラー

コンテンツをIntercomに移行した後、記事のURLが機能しなくなった場合：

Help Centerの公開URLで「Not found」エラーが表示されるが、ワークスペース内で記事が正しく表示される場合：

APIの現在のバージョンは2.15です。APIのドキュメントはdeveloper documentation siteでご覧いただけます。Developer Hubでこのガイドの手順に従って使用バージョンを変更することも可能です。

Intercom APIを使用している場合、リクエストのHTTPヘッダー内でもバージョンを変更できます。

Intercom APIバージョン2.15で利用可能なエンドポイントは以下の通りです。

はい、Messengerで記事をトリガーしたい場合は、JavaScript APIのshowArticle メソッドを使用できます。記事はMessenger内で開き、Messengerの戻るボタンをクリックすると前のコンテキストに戻ります。メソッド呼び出し時にMessengerが閉じている場合は、最初に開いてから記事を表示します。これはMessengerのすべてのプラットフォームで利用可能です。

Intercomではusersはcontactsのラベルに分類されます。APIでcontactsを一括作成するエンドポイントはありませんが、create contacts endpointを使ってユーザーをインポートするスクリプトを作成したり、このチュートリアルでコードサンプルを参照できます。

レート制限チェックを必ず設定し、現在は各アプリで1分あたり10,000 APIコール、各workspaceで1分あたり25,000 APIコールの制限を超えないようにしてください。

Intercom APIにはcontactsの専用一括作成エンドポイントはありません。大量のcontactsをインポートするには、create contact endpointをループで使用し、適切なレート制限を守ってください（アプリごとに1分あたり10,000 APIコール、workspaceごとに1分あたり25,000コール）。

以下の一括操作はAPIでは利用できません。ループでの単一リクエストか手動のエクスポート/インポートで対応してください。

アーカイブされたcontactのデータを取得するには、まずcontactをアンアーカイブする必要があります。contactのIDがあればunarchive contact API endpointで可能です。

その後、get a contact API endpointでcontactのデータにアクセスでき、retrieve a conversation API endpointで会話を取得できます。

いいえ、現在APIで個別のノート削除や一括削除はできません。この機能が必要な場合はProduct Wishlistで機能リクエストを作成、コメント、投票してください。ノートはworkspace内で手動で1件ずつ削除可能です。

APIで会話をチームに割り当てるには2つの方法があります。

1つ目はmanage a conversation API endpointを使い、会話を直接adminまたはチームに割り当てる方法です。会話のIntercom provisioned id、admin_id、assignee_idが必要です。

もう1つはrun assignment rules on a conversation API endpointを使い、既に設定済みの割り当てルールを会話に適用する方法です。会話のIntercom provisioned idが必要です。

機能は開発者ドキュメントの「Try It」機能、Intercom Postman collection、またはご自身のターミナルやIDEで試せます。Intercomのアクセストークンをベアラートークンとして使用するのを忘れずに。

ノートはチームメンバーだけが見られる内部コメントです。会話にノートを追加するにはreply to a conversation API endpointを使います。message_typeにnote、typeに"admin"、そしてノートの発信元admin_idを指定してください。

機能は開発者ドキュメントの「Try It」機能、Intercom Postman collection、またはご自身のターミナルやIDEで試せます。Intercomのアクセストークンをベアラートークンとして使用するのを忘れずに。

UIで既にタグを作成していれば、そのタグを会話に適用できます。またAPIで新しいタグを作成することも可能です。

add tag to a conversation API endpointを使うには、タグ付けする会話のconversation_id、タグのIntercom provisioned id、admin_idが必要です。

機能は開発者ドキュメントの「Try It」機能、Intercom Postman collection、またはご自身のターミナルやIDEで試せます。Intercomのアクセストークンをベアラートークンとして使用するのを忘れずに。

APIでcontact（userまたはlead）が開始した会話を作成するには、create a conversation API endpointを使います。会話はアプリ内メッセージのみです。

リクエスト時にはcontactのIntercom provisioned idとメッセージ本文のテキストが必要です。

機能は開発者ドキュメントの「Try It」機能、Intercom Postman collection、またはご自身のターミナルやIDEで試せます。Intercomのアクセストークンをベアラートークンとして使用するのを忘れずに。

APIで会話を終了するにはmanage a conversation API endpointを使います。会話のIntercom provisioned id、admin_idが必要で、message_typeに"close"を指定してください。

会話の一部だけを編集する必要がある場合はredact a conversation part API endpointを使ってください。

機能は開発者ドキュメントの「Try It」機能、Intercom Postman collection、またはご自身のターミナルやIDEで試せます。Intercomのアクセストークンをベアラートークンとして使用するのを忘れずに。

チームメンバーが会話に割り当てられたなどのアクション時にカスタム通知を設定するには、webhooksを使用します。

conversation.admin.assigned会話トピックを使います。すべての会話トピックは開発者ドキュメントで確認できます。

このガイドの手順に従い、開発者ハブでこのwebhookトピックを購読してください。通知を届けるために、webhookが発動した際にアクションを実行する公開可能なエンドポイントURLも必要です。

side conversationsには専用のエンドポイントがないため直接取得できません。ただし、side conversationが付随する会話を取得すると、"part_type": "side_conversation_reply"として表示され、side conversation内のユーザーメッセージ内容が確認できます。

Intercom APIでticketを作成するには、まず新しいticketにラベル付けするticketタイプを作成または取得する必要があります。その後、curlリクエストや任意のプログラミング言語でticketを作成できます。

開発者ドキュメントのこのガイドに従い、ticketタイプを作成し新しいticketを作成してください。

APIを使用してticketsやticketデータを取得する場合は、search tickets APIエンドポイントを使用できます。バックオフィスのticketタイプを除外するには、フィールドにticket_type_idを設定し、!=演算子を使ってバックオフィスのticketタイプに割り当てられたticket_type_idを除外してください。

APIを使用して会話を取得したり、会話を一覧表示したりして、会話に関連付けられたバックオフィスのticketを除外したい場合は、同様にバックオフィスのticketタイプを属性として持つ結果をフィルタリングできます。リンクされたticketはレスポンスのticketsパラメータまたはlinked_objectsにあります。

もう一つの方法として、APIを使って会話にバックオフィスのticketをタグ付けすることができます。そのタグを使ってticketカテゴリでフィルタリングできます。

レスポンスで403 API Plan restrictedメッセージが表示される場合、それは使用しようとしているAPIがあなたのアプリのプランで利用できないことを意味します。

APIにアクセスするにはプランをアップグレードする必要があります。Intercomのプランについてはこちらのページで詳しくご覧いただけます。エラーコードの完全なリストはこちら、HTTPレスポンスのリストはこちらの開発者ドキュメントでご確認いただけます。

レスポンスで409 conflictメッセージが表示される場合、それはIntercomワークスペース内にリクエストデータと衝突する既存のデータがあることを意味します。例えば連絡先を作成しようとして、そのメールアドレスの連絡先がすでにアプリ内に存在する場合に発生します。

このエラーを回避するには、代わりに更新エンドポイントを使用するか、user_idで新しい連絡先を作成してください。エラーコードの完全なリストはこちら、HTTPレスポンスのリストはこちらの開発者ドキュメントでご確認いただけます。

429メッセージが表示される場合、それはクライアントがレート制限に達したか超過したか、またはサーバーが過負荷状態であることを意味します。各アプリには、1分あたり10,000回のAPIコールのデフォルトレート制限と、ワークスペースごとに1分あたり25,000回のAPIコールの制限があります。レート制限の詳細は開発者ドキュメントでご覧いただけます。

このエラーを回避するには、レート制限チェックを設定して制限に達していないことを確認してください。エラーコードの完全なリストはこちら、HTTPレスポンスのリストはこちらの開発者ドキュメントでご確認いただけます。

プライベートアプリは、アプリごとに1分あたり10,000回、ワークスペースごとに1分あたり25,000回のデフォルトレート制限があります。つまり、ワークスペースに複数のプライベートアプリがインストールされている場合、それぞれがリクエスト数の合計に寄与します。

パブリックアプリは、アプリごとに1分あたり10,000回、ワークスペースごとに1分あたり25,000回のデフォルトレート制限があります。つまり、ワークスペースに複数のパブリックアプリがインストールされている場合、それぞれが独自のリクエスト制限を持ち、他のアプリの制限には影響しません。レート制限の詳細は開発者ドキュメントでご覧いただけます。

APIを使って独自のレポートを作成する場合、2つのレポートに違いがあることがあります。これはいくつかの理由によるものです。

よくある問題の一つは、日付と時刻が一致しないことです。これは、Intercomワークスペースで使用しているタイムゾーンとAPIクエリで使用しているタイムゾーンが異なるために起こります。これを修正するには、APIクエリパラメータをワークスペースのタイムゾーンに合わせるか、カスタムレポートのタイムゾーンを変更してください。

もう一つの問題は、IntercomのレポーティングUIのメトリクスと一致しないメトリクスを使用している可能性があることです。レポーティングUIで利用可能な一部のメトリクスは計算済みメトリクスであるため、APIでは利用できません。それらの一部はAPIを使って取得し、独自に計算することが可能です。Intercom開発者ドキュメントの独自レポート作成ガイドをご覧ください。

UIで利用可能な会話レポートと会話APIを使って取得したレポートで会話数に違いがあることがあります。これは、会話に関連付けられたバックオフィスのticketがAPIから取得した際に含まれるためです。

これを解決するには、list conversations、retrieve a conversation、またはsearch for conversations APIで結果を取得後にフィルタリングし、conversation APIレスポンスのticketフィールドを使ってticketと会話を分けることができます。ticketフィールドはticketの場合はオブジェクトが入り、会話の場合はnullになります。

Webhookは、contactが作成されたり、受信メッセージが届いたりするなど、Intercomで発生するイベントのリアルタイム通知を購読できる機能です。

各バージョンで利用可能なwebhookは開発者ドキュメントで確認できます。必要なwebhookがわかったら、このガイドに従って設定してください。

新しいwebhookを追加する予定はありませんが、必要なwebhookがある場合はチームにリクエストを送るか、Intercomコミュニティの製品ウィッシュリストに追加してください。

Intercomのwebhookを構築する際は、以下に注意してください。

IntercomのAPIはリストや検索リソースにカーソルベースのページネーションを提供しています。大量のデータ（多くの会話とそのすべてのパーツなど）をリクエストする際に、小分けに受け取り処理できるようにするためです。

IntercomのリストAPI（パスパラメータ使用）と検索API（クエリパラメータ使用）の両方でページネーションを使う例はページネーションガイドをご覧ください。

カーソルベースのページネーションでは、Intercomはリクエストごとに指定したページ数の制限に基づいて特定のレコードを指すポインタを使用します。

オブジェクトで返される場合、ポインタは「WzXXXXXXXXXXXXXX」のように見えます。

その後、レスポンスのポインタを使って次のデータバッチのリクエストを行えます。

リクエストのページネーション形式はリストAPIと検索APIで若干異なりますが、レスポンスは同じように動作します。

curlリクエストの例はページネーションページで、リストAPIと検索APIの使い方チュートリアルもあります。

サードパーティのworkspaceデータと連携するアプリやCanvas Kitで作られたアプリはOAuthが必要です。ユーザーにアクセストークンを直接尋ねることはせず、OAuthのみを使ってデータとやり取りしてください。

OAuthの設定方法については、ドキュメントをご覧ください。

他の人のIntercomデータにアクセスする統合をIntercomで構築する場合は、OAuthの設定が必要です。これは、Intercomアプリストアに掲載予定の公開アプリや、ユーザーに自社ウェブサイト経由でインストールを依頼するアプリや統合が含まれます。OAuthの詳細は開発者ドキュメントをご覧ください。

自分のIntercomワークスペース内のデータにのみアクセスする場合は、アクセストークンを使用できます。

自分のIntercomワークスペース内のデータにのみアクセスするプライベートアプリを構築する場合は、Intercomのアクセストークンを認証に使用できます。開発者ハブでアクセストークンを見つけ、認証について詳しくはこちらをご覧ください。

APIを使って自分のIntercomワークスペースのデータにアクセスする場合は、Intercomのアクセストークンを使用できます。開発者ハブでアクセストークンを見つけ、認証について詳しくはこちらをご覧ください。

APIアクセストークンを見つけるには、以下の手順に従ってください：

はい、Intercom Supportに依頼すれば、アプリのOAuthクライアントシークレットをローテーションできます。ローテーション後、古いシークレットは即座に無効になり、新しいシークレットはDeveloper Hubで利用可能です。

ローテーションを依頼するには、アプリの詳細を添えてIntercom Supportに連絡してください。ローテーションが行われた瞬間に古いシークレットは無効になるため、新しいシークレットで統合の設定をすぐに更新できるようチームを準備させてください。

Canvas Kitを使って、Intercom Inbox内で直接動作するアプリを作成できます。

このチュートリアルに従って、最初のInboxアプリの作り方を学びましょう。Canvas Kitの詳細やリファレンスドキュメントは開発者ドキュメントでご覧いただけます。

Canvas Kitを使って、Intercom Messenger内で直接動作するアプリを作成できます。

カスタマイズはCanvas Kitで可能な範囲に限られ、Messenger内で作成する必要があります。Messengerの再作成やスキン変更はできません。

このチュートリアルに従って、最初のInboxアプリの作り方を学びましょう。Canvas Kitの詳細やリファレンスドキュメントは開発者ドキュメントでご覧いただけます。

Developer HubのTest & Publish > Your Workspacesページにアクセスすると、あなた（Intercomチームメンバー）が所属するすべてのワークスペースが表示されます。

インストールしたいワークスペースの横にある「Install app」をクリックすると、そのアプリがインストールされます。そのワークスペースのデータにAPI経由でアクセスできるように、Access Tokenが提供されます。

サードパーティのインストール手順については、開発者ドキュメントをご覧ください。

公開の準備ができたら、開発者ハブの手順に従ってください。開発者ドキュメントに公開方法のガイドがあります。

iOS用Intercom SDK（ソフトウェア開発キット）を使うと、アプリ内でIntercom Messengerを利用し、顧客と会話したり、リッチなアウトバウンドメッセージを送信したり、Help Centerを表示したり、イベントを追跡したりできます。

Cocoapods、Swift Package Manager、または手動でiOS用Intercomをインストールできます。iOSインストールガイドをお読みください。GitHubのIntercom for iOSとサンプルアプリもご覧いただけます。

Android用Intercom SDKを使うと、アプリ内でIntercom Messengerを利用し、顧客と会話したり、リッチなアウトバウンドメッセージを送信したり、Help Centerを表示したり、イベントを追跡したりできます。

Gradleまたは手動でAndroid用Intercomをインストールできます。Androidインストールガイドをお読みください。GitHubのIntercom for Androidとサンプルアプリもご覧いただけます。

Intercom React Nativeラッパーを使うと、React NativeアプリでiOS用IntercomとAndroid用Intercomを利用できます。React Nativeインストールガイドに従って始めてください。