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

アプリ開発用に新しいdeveloper workspaceを作成できます。developer workspaceは無料で、開発目的専用です。新しい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（米国リージョン） • Manual/HTTP Setupの場合：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. Domainが安全でない

ERR_SSL_VERSION_OR_CIPHER_MISMATCHエラー

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

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

4. アクセス拒否エラー

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

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

Help Centerで予期しない動作があった場合は、設定を調査する前にこれらの手順から始めてください。

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は連絡先のラベルに含まれます。APIで連絡先を一括作成するエンドポイントはありませんが、連絡先作成エンドポイントを使ってユーザーをインポートするスクリプトを作成するか、このチュートリアルに従ってコードサンプルを取得できます。

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

アーカイブされた連絡先のデータを取得するには、まず連絡先のアーカイブを解除する必要があります。連絡先のIDがあれば、unarchive contact API endpointを使って解除できます。

その後、get a contact API endpointを通じて連絡先のデータにアクセスでき、retrieve a conversation API endpointを通じて会話にアクセスできます。

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

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

1つ目はmanage a conversation API endpointを使って会話を管理し、管理者またはチームに直接割り当てる方法です。会話の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を使って、連絡先（ユーザーやリード）が開始した会話を作成できます。create a conversation API endpointを使用します。会話はアプリ内メッセージのみです。

リクエスト時に使用するメッセージ本文のテキストと連絡先の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も必要です。

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

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

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

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

APIで会話を取得または会話一覧を取得し、バックオフィスのTicketsが関連付けられている場合、それらを除外したい場合は、同様にバックオフィスのチケットタイプを属性として持つ結果をフィルタリングできます。リンクされた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は、連絡先が作成されたり受信メッセージが届いたりするなど、Intercomで発生するイベントのリアルタイム通知を購読できる機能です。

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

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

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 Client Secretをローテーションできます。ローテーション後、古いシークレットは即座に無効になり、新しいシークレットはDeveloper Hubで利用可能です。

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

Canvas Kitを使ってIntercom Inbox用のアプリを作成できます。これはIntercom UI内で直接動作するアプリを作るためのツールキットです。

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

Canvas Kitを使ってIntercom Messenger用のアプリを作成できます。これはIntercom UI内で直接動作するアプリを作るためのツールキットです。

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

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

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

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

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

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

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

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

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

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

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