以下に関するよくある質問への回答です：

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

本番用ワークスペースで新しいアプリを作成し、アクセス トークンを取得するには、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を設定します。設定手順は開発者ドキュメントをご覧ください。

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

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

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

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

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

SSL設定については開発者ドキュメントのガイドに従ってください。プロバイダーによって設定手順が異なる場合があります。

1. Domainが安全でない

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

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

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

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

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

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

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

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

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

APIを使用して会話をチームに割り当てたい場合、2つのオプションがあります。

最初のオプションは、manage a conversation API endpointを使用して、会話を直接管理者またはチームに割り当てることです。会話のIntercom provisioned id、admin_id、およびassignee_idにアクセスできる必要があります。

もう一つのオプションは、run assignment rules on a conversation API endpointを使用して、既に設定した割り当てルールを会話に適用することです。会話のIntercom provisioned idにアクセスできる必要があります。

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

メモはチームメンバーだけが見られる内部コメントです。会話にメモを追加するには、reply to a conversation API endpointを使用できます。messsage_typeにnoteを、typeに「admin」を選び、メモの発信元となるadmin_idを指定する必要があります。

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

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

add tag to a conversation API endpointを使用するには、タグを付ける会話のconversation_id、タグのIntercom provisioned id、およびadmin_idにアクセスできる必要があります。

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

APIを使って、コンタクト（ユーザーまたはリード）から開始された会話を作成できます。create a conversation API endpointを使用します。会話はアプリ内メッセージのみ可能です。

会話を開始するには、コンタクトのIntercom provisioned idと本文テキストも必要です。

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

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

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

次に、このガイドの手順に従って、開発者ハブでこのwebhookトピックを購読します。通知を配信するために、webhookがトリガーされたときにアクションを実行するための公開可能なエンドポイントURLも必要です。

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

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タイプを属性として持つ結果を同様にフィルタリングできます。リンクされたticketはレスポンスのticketsパラメータまたはlinked_objectsの下にあります。

もう一つの方法は、APIを使ってback office 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で利用可能な会話レポートとconversations APIを使って取得したレポートを比較すると、会話数に違いがあることに気づくかもしれません。これは、会話に関連付けられたバックオフィスのticketsがAPIから取得する際に含まれるためです。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

このチュートリアルで最初のInboxアプリの作り方を学べます。Canvas Kitの詳細やリファレンスは開発者ドキュメントをご覧ください。

Canvas Kitを使って、Intercom UI内で直接動作する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を使うと、アプリ内でIntercom Messengerを利用し、顧客と会話したり、リッチなアウトバウンドメッセージを送信したり、Help Centerを表示したり、イベントを追跡したりできます。

Cocoapods、Swift Package Manager、または手動でiOS用Intercomをインストールできます。詳細はこちらをご覧ください。iOS用IntercomはGitHubで入手でき、SDKを試せるサンプルアプリもこちらにあります。

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

Gradleまたは手動でAndroid用Intercomをインストールできます。詳細はこちらをご覧ください。Android用IntercomはGitHubで入手でき、SDKを試せるサンプルアプリもこちらにあります。

Intercom React Nativeラッパーを使うと、React NativeアプリでiOS用IntercomとAndroid用Intercomを利用できます。セットアップ手順はこちらをご覧ください。