この記事では、Intercom開発環境のセットアップ、SSL付きのカスタムHelp Center domainの設定、アクセス・トークンや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で「見つかりません」エラーが表示されるが、ワークスペース内で記事が正しく表示される場合：

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提供ID、admin_id、assignee_idへのアクセスが必要です。

もう1つの方法は、run assignment rules on a conversation API endpointを使って、既に設定した割り当てルールを会話に適用することです。会話のIntercom提供IDへのアクセスが必要です。

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

ノートはチームメイトだけに見える内部コメントです。会話にノートを追加するには、reply to a conversation API endpointを使います。message_typeにnote、typeに「admin」、ノートの発信元となるadmin_idを指定する必要があります。

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

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

add tag to a conversation API endpointを使うには、タグ付けする会話のconversation_id、タグのIntercom提供ID、admin_idへのアクセスが必要です。

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

APIを使って、連絡先（ユーザーまたはリード）が開始した会話を作成できます。create a conversation API endpointを使用します。会話はアプリ内メッセージのみ可能です。

リクエスト時に使用するメッセージ本文のテキストと連絡先のIntercom提供IDも必要です。

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

APIを使って会話を終了するには、manage a conversation API endpointを使用します。会話のIntercom提供ID、admin_idが必要で、message_typeに「close」を指定します。

会話の一部だけを編集したい場合は、redact a conversation part API endpointを使用してください。

機能は開発者ドキュメントの「Try It」機能、Intercom Postmanコレクション、またはご自身のターミナルや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パラメータまたは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アクセストークンを見つけるには、以下の手順に従ってください：

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を通じてデータにアクセスできます。

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

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

iOS用Intercom SDK（Software Development Kit）を使うと、アプリ内で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インストールガイドに従って始めましょう。