この記事では、Intercom 開発者環境の設定、カスタム Help Center domain の SSL 設定、アクセス トークンまたは OAuth によるアプリ認証、Intercom API を使った連絡先、会話、tickets の管理方法を説明します。webhooks、ページネーション、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 を使いたい場合は、カスタム domain を手動で設定して作成できます。Help Center 設定でカスタム domain を入力し、カスタム CNAME レコードを作成し、必要に応じて SSL を設定します。設定手順はdeveloper documentationにあります。 カスタム domain 設定後に Help Center で「not found」エラーが出る場合は、CNAME レコードが正しい Intercom ホストを指しているか確認してください。 • HTTPS Quick Setup 用: us.intercomhelpcenter.com（米国リージョン） • Manual/HTTP Setup 用: custom.intercom.help（米国リージョン） また、Help Center 設定のセキュリティ プロトコルが DNS 設定と一致しているかも確認してください。

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

カスタム domain 上の Articles で SSL を設定する方法は2つあります。

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

カスタム domain を HTTPS に切り替えたい場合：

カスタム domain の SSL を設定して機密情報を暗号化できます。これを行う場合は、Cloudflare のように SSL をサポートする DNS プロバイダーで CNAME を設定してください。

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

標準の SSL と HTTPS 設定で問題が解決しない場合、カスタム Help Center domain に関する一般的な例外ケースを以下に示します。

1. Domain が安全でない

ERR_SSL_VERSION_OR_CIPHER_MISMATCH エラー

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

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

4. アクセス拒否エラー

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

Help Centerの公開URLで「見つかりません」エラーが表示されるが、ワークスペース内で記事が正しく表示される場合：

APIの現在のバージョンは2.15です。APIのドキュメントは開発者ドキュメントサイトでご覧いただけます。また、開発者ハブでこのガイドの手順に従って、アプリで使用するバージョンを変更できます。

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

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

はい。Messengerで記事を開くには、JavaScript APIのshowArticle メソッドを使用できます。記事はMessenger内で開き、Messengerの戻るボタンをクリックすると前の画面に戻ります。Messengerが閉じている場合は、メソッド呼び出し時にまず開き、その後記事が表示されます。これはMessengerのすべてのプラットフォームで利用可能です。

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

レート制限チェックを設定して、現在1アプリあたり毎分10,000 APIコール、ワークスペースあたり毎分25,000 APIコールの制限に達していないことを確認してください。

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

以下の一括操作はAPIでは利用できず、ループでの単一アイテムリクエストか手動のエクスポート/インポートで対応する必要があります。

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

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

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

APIで会話をチームに割り当てたい場合、2つの方法があります。

1つ目はmanage a conversation API endpointを使い、会話を直接adminまたはteamに割り当てる方法です。会話の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を使います。messsage_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 don't have their own dedicated endpoint, so you can’t retrieve them directly. However, when you retrieve a conversation that the side conversation is attached to, you will see conversation parts that show as "part_type": "side_conversation_reply" with the content of the user's messages in the side conversation.

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

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

APIでTicketsやTicketデータを取得する場合、search tickets API endpointを使えます。back office Ticketタイプを除外するには、フィールドにticket_type_idを設定し、!=演算子でback office Ticketタイプのticket_type_idを除外してください。

APIで会話を取得または会話一覧を取得し、back office Ticketsが関連付けられている場合、それらを除外したい場合は、back office Ticketタイプを属性として持つ結果を同様にフィルタリングできます。リンクされたTicketsはレスポンスの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回のAPIコール、ワークスペースごとに1分あたり25,000回のAPIコールのデフォルトレート制限があります。つまり、ワークスペースに複数のプライベートアプリがインストールされている場合、それぞれがリクエストの合計数に寄与します。

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

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

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

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

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

これを解決するには、list conversations、retrieve a conversation、またはsearch for conversations APIで結果を取得した後にフィルタリングし、会話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の使い方チュートリアルもあります。

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

OAuth設定の手順はドキュメントをご覧ください。

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

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

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

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

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

はい、Intercom Supportはリクエストに応じてアプリのOAuthクライアントシークレットをローテーションできます。ローテーション後、古いシークレットは直ちに無効になり、新しいシークレットはDeveloper Hubで利用可能です。

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

Canvas Kitを使用して、Intercom UI内から直接動作するアプリを作成することで、Intercom Inbox用のアプリを作成できます。

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

Canvas Kitを使用して、Intercom UI内から直接動作するアプリを作成することで、Intercom Messenger用のアプリを作成できます。

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

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

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

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

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

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

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