この説明では、Data connectors を設定、構成、管理する方法を説明します。Data connectors は Fin が外部システムから最新データを取得し、チームメンバーの対応を待たずに顧客にパーソナライズされた回答を提供できる機能です。テンプレートからまたは一からコネクタを作成する方法、API エンドポイントの構成、レスポンスの整形、トリガー可能なユーザーの制御、セキュリティ処理、安全なロールアウト、パフォーマンスの監視方法を学びます。

注：Data connector を作成、編集、または公開するには、"Can access developer hub" の権限が必要です。

Data connectors はどのように機能しますか？

各 Data connector は、設定する API（application programming interface）コールで構成されます。Fin は自動的にいつ使用するかを判断して顧客固有の回答を提供します。API を持つあらゆるシステムを接続できます。例として：

カスタムの社内バックエンドツール
サードパーティプラットフォーム（Shopify、Salesforce、Stripe、Jira など）

図：Data connector が Intercom の Fin AI エージェントを API コール経由で外部システムに接続し、顧客固有のデータを取得して応答に含める仕組みを示す。

ヒント：Data connectors は、Procedures や他の自動化（Workflows や Inbox の macros を含む）で Fin によって使用できます。Data connectors と API の設計と使用方法の詳細は、こちらを参照してください。

Data connector を作成する方法

Settings > Integrations > Data connectors に移動し、New をクリックします。

Settings > Integrations > Data connectors の Data connectors ページのスクリーンショット（New ボタンが強調表示されています）。

サポートされているアプリのいずれかがインストールされている場合、Create Data connector の下にそのアプリ用のテンプレートが表示されます。テンプレートは現在 Shopify、Stripe、Statuspage 用に利用可能です。詳細は下記のサードパーティのテンプレートからを参照してください。

サードパーティのテンプレートから

次のアプリがワークスペースにインストールされている場合、Data connector テンプレートが利用可能です：

アプリがまだインストールされていない場合は、App Store に移動してインストールしてください。インストール後、各アプリ用の Data connectorテンプレートが Data connector として表示され、すぐに公開できるようになります。

テンプレートをクリックすると、Data connector の機能に関する情報が表示され、Messenger プレビューでテストできます。動作に満足したら、Set live for AI Agent を選択します。

Data connector テンプレートカードのスクリーンショット。Messenger に表示される Fin の応答プレビューと「Set live for AI Agent」ボタンが表示されています。

ここでの Messenger プレビューはサンプルデータを使用しています。Data connector を公開すると、Fin は実際の顧客データを使用します。

Data connector を構成したい場合は、Customize をクリックすると詳細な構成のための Data connector ビルダーに移動します。

サポートされているアプリがインストールされていない場合、ここにアプリが表示されるのでワークスペースにインストールできます。インストール後、関連する Data connector テンプレートが上記セクションに表示されます。

利用可能な Data connectorテンプレートと Fin のユースケースについて詳しくは、こちらを参照してください。

AI 推奨から

AI 推奨の Data connector を確認するには、Settings > Integrations > Data connectors に移動し、New Data connector. をクリックします。

"Create Data connector from template" の下に、あなた専用の AI 推奨 Data connector が表示されます。これらは会話履歴に基づいて生成され、解決可能な会話量の割合の見積もりや Messenger プレビューを事前に確認できます。

AI 推奨を表示するには、Fin がワークスペースで稼働しており、十分な会話量が必要です。

AI 推奨の Data connector をクリックすると、その機能に関する情報が表示され、（サンプルデータを使用して）Messenger でプレビューできます。AI 推奨の Data connector は会話量に基づく提案に過ぎず、実際に機能させるには手動で API を接続する必要があります。

Data connector を公開するには、Set up をクリックして API の詳細を構成します。

AI 推奨 Data connector カードのスクリーンショット。説明、推定会話カバレッジ割合、Messenger プレビューが表示されています。

あとは、HTTPS URL を追加して Data connector を API に接続するだけです。

この Data connector をさらにカスタマイズするには、カスタム Data connector からセクションを参照してください。

カスタムの Data connector を一から作成する

独自のカスタム Data connector を Fin 用に設定するには、Settings > Integrations > Data connectors に移動し、+ New > + Create from scratch をクリックします。

新しい Data connector 画面のスクリーンショット。'Create from scratch' が選択され、API、Data、Fin、Security の4フェーズセットアップタブが表示されています。

フェーズ 1：API

API タブは、Intercom が外部システムと通信する方法を定義します。

API タブの Identity セクションのスクリーンショット。コネクタ名と内部説明のフィールドが表示されています。

コネクタに短く説明的な名前を付けます。例："Get unpaid account balance."。これにより Fin が使用タイミングを理解しやすくなります。チーム参照用に内部説明を追加してください。

Data connector の説明を書く際のベストプラクティスは、こちらを参照してください。

注：Data connector 名には絵文字はサポートされておらず、含めるとエラーになります。

データ入力

データ入力では、コネクタが実行される前に Fin が収集する必要のある情報を指定できます。例えば、顧客のアカウント番号が Intercom に保存されていない場合です。ユーザーの問い合わせに基づいて Fin が検索クエリやその他の値を API に渡す必要がある場合は、データ入力を追加し、ソースを Let Fin collect に設定してください。Fin は会話から自動的に値を収集します。

Data inputs セクションのスクリーンショット。名前、説明、フォーマットタイプ、ソースオプションを含むサンプル入力フィールドが表示されています。

+ Data input をクリックして形式を選択：

テキスト
数値
小数
真/偽

各入力項目に名前と説明を付けて、Fin が収集方法を把握できるようにしてください。API が null または応答を返さない場合に備えて、フォールバック値を設定することもできます。

各入力について、データの取得元を選択してください：

データ入力ソースのドロップダウンのスクリーンショット。3つのオプションが表示されています：Let Fin collect、People attribute、Custom value。

Let Fin collect — Fin が会話から自動的に収集します
People attribute — 既存の Intercom 属性から取得します
Custom value — あなたが定義する固定値

ソースを選択したら、Required トグルでその入力が必須か任意かを設定します。これは各入力ごとに手動で設定する必要があります（状態は自動的に設定されません）。

トグルのラベルは選択されたソースにより変わります：

Let Fin collect：トグルの表示は Fin must collect this parameter となります。有効にすると、コネクタが実行される前に Fin がこの値を顧客から収集する必要があります。
People attribute または Custom value：トグルの表示は This parameter must have a value となります。有効にすると、値が欠落している場合コネクタは実行されません。

各入力の必須/任意の状態はデータ入力リストに表示されます。

API endpoint

API エンドポイントの HTTPS（セキュア Web）URL を追加し、HTTP リクエストメソッドを選択します：GET（データ取得）、POST（データ送信）、PUT（置換）、DELETE（削除）、または PATCH（部分更新）。

API エンドポイントセクションのスクリーンショット。HTTPS URL 用のテキストフィールドと HTTP メソッド（GET、POST、PUT、DELETE、PATCH）のドロップダウンが表示されています。

Attribute Inserter を使って、顧客の user ID のような動的値を URL パスやリクエストボディに直接渡します。属性は必ずピッカーで選択し、トークンを手入力しないでください。

Note: コネクタが Intercom Contacts API を呼び出して連絡先を識別する必要がある場合は、ピッカーから Contact ID（user.id）を選択してください。User ID（user_id）ではありません。Contacts API は Intercom が生成した連絡先 ID（user.id）を期待します。外部で設定された ID（user_id）を使用すると検索に失敗します。

Important: エディタは {{...}} テキストをピルに変換するため、手入力されたトークンは有効な属性と見た目が同じになります。識別子が user.id や user_id のような実在の属性と一致しない場合、実行時に空の値に解決されます。これによりリクエスト URL が不正になり、エディタ上で表示されない 404 のようなエラーが発生します。属性を挿入する際は常に Attribute Inserter のピッカーを使用してください。

Authentication and headers

認証トークンを選択し、API が必要とするカスタムのキーと値のヘッダーを追加します（例：Content-Type: application/json）。

Note: JSON リクエストボディ（POST、PUT、PATCH）を送信する場合は、Content-Type: application/json ヘッダーを明示的に追加する必要があります。これがないと受信側 API はリクエストボディを解析できず、JSON が正しくフォーマットされていてもすべてのフィールドを無効として拒否します。

認証とヘッダーのセクションのスクリーンショット。トークンセレクターとカスタム HTTP ヘッダー用のキー・バリューエディタが表示されています。

Note：単一のコネクタに複数のトークンを添付できます。各トークンは異なるヘッダキーを使用する必要があります — 添付されたすべてのトークンはすべてのリクエストと共に送信されます。

エンドポイント URL と認証の詳細を入力したら、Test connection をクリックして設定を検証します。成功すると緑の確認と生の API 応答が返されます。失敗すると HTTP エラーコードと説明が表示されます — Phase 2: Data へ進む前にエラーを解消してください。

Test connection 結果パネルのスクリーンショット。緑の成功ステータスと生の JSON API 応答が表示されています。

Phase 2: Data — API 応答の整形

Data タブでは、Fin が顧客に回答する前に API 応答をどのようにフィルタおよび変換するかを制御します。表示フィールドを制限したり、ビジュアルエディタや Python コードでデータの形を変えることができます。

Restrict and shape

デフォルトでは、Fin は完全な API 応答にアクセスできます。Fin が読み取る内容を制限するには、Manually restrict access に切り替え、公開するフィールドのみを選択してください。

Note: Manually restrict access を使用する場合、フィールド名に括弧 ()、プラス記号 +、スラッシュ / などの特殊文字が含まれていると、パスマッチングのバグにより Fin が受け取るデータから静かに除外されることがあります。この回避策として、制限する前に対象フィールドの特殊文字を削除して名前を変更してください。あるいは、応答に機密データが含まれていない場合は完全なデータアクセスを使用してください。

応答をどのように変換するかを選択してください：

Table view — フィールドをフィルタ、名前変更し、ビジュアルエディタでフィールドレベルの変換を設定します
Python — Fin に届く前に応答をクリーン、整形、再フォーマットするための Python コードを記述します

Object mapping

Object mapping を使うと、API 応答フィールドを Intercom の連絡先または会社属性に直接マッピングでき、外部システムから Intercom ワークスペースへ自動的にデータを同期できます。

Test code をクリックして Python 変換ロジックを検証し、Test connection で完全な API 呼び出しと応答の形状を確認します。Phase 3: Fin に進む前にエラーを解消してください。

Note: Object mapping を選択すると、Workflows と Procedures ではマッピングされたオブジェクトのみが表示されます。マッピングしない場合は、Restrict and shape the data テーブルで選択されたすべてのオプションが一覧表示されます。Python の場合は、返された値のみが表示されます

Phase 3: Fin — Fin がコネクタをトリガーする方法

Fin タブでは、Fin がデータコネクタを自動的にトリガーするか、ワークフロー、プロシージャ、または macro から明示的に呼び出された場合のみかを制御します。コネクタの感度や書き込みの活発さに合わせてトリガーモードを選択してください。

Tip: Fin がコネクタを使用できるようにするには、次の各項目が整っていることを確認してください：

Data inputs: Fin が API に渡す必要がある任意の値（検索クエリ、製品名、注文 ID など）については、ソースを Let Fin collect に設定したデータ入力を追加してください。これにより Fin は会話から関連する用語を収集し、自動的に API に渡します。
Test connection: フェーズ 1 で実際のデータを使って成功するテストを実行してください。テスト応答は Fin が参照して顧客に返すものの形を決定します — サンプルデータは実際の結果を反映しません。
Fin trigger: この Fin タブで、How should Fin use this connector? を Enabled (direct trigger) に設定します。
Connector description: コネクタが何を行い、いつ使用するかを明確かつ集中して記述してください。これが Fin が呼び出すタイミングを決めます。
Set live: Phase 4 のセキュリティチェックを完了したら、Save をクリックし Set live してください。

How should Fin use this connector?

Enabled (direct trigger)

Fin は顧客の質問に基づいてコネクタを自動的にトリガーします — ワークフローは不要です。読み取り専用のコネクタ（例：「注文状況の確認」）や大量の繰り返しクエリに最適です。

この Data connector を利用できる対象は、reusable Fin audiences や、このコネクタ専用のカスタムオーディエンスを作成することで制御できます。例えば、「Enterprise plan」オーディエンスの顧客に利用可能にしたり、ログインして確認済みメールを持ち、アカウント残高について問い合わせる users のみを対象とするカスタムオーディエンスに制限したりできます。

注意：Data connectors で Fin audiences を使えるようになりました。Fin audiences は一度作成して複数のコネクタで適用できる再利用可能な顧客グループで、一貫性を保ちやすくします。

Everyone、再利用可能な Fin audience、または一時的なルール用の Custom オーディエンスを選択できます。
複数の Fin audiences を選択できますが、Custom ルールと Fin audience を組み合わせることはできません。
既存の Data connector のオーディエンスルールは、機能を保持するために Custom オーディエンスに変換されます。

ヒント：Data connector を顧客向けに有効化する前にテストしたい場合は、まずオーディエンスルールで自分やチームメンバーだけに Data connector を有効にしてください。

Disabled (manual trigger)

コネクタは自動で実行されません。Workflow、Procedure、または Macro に手動で追加する必要があります。削除アカウントのような感度が高い、または書き込みを伴うコネクタには、実行前に人間やワークフローの監視が入ることを望む場合に最適です。

Fin プレビューを使用すると、このコネクタを使った場合に Fin がどのように応答するかを実際に確認できます。

注意：Fin トリガー設定への変更は下書きモードで保存され、公開するまで有効になりません。コネクタのライブ版は、Set live をクリックするまで既存の設定を使用し続けます。変更後は、必ず下書きだけでなくライブ版にも設定が反映されていることを確認してください。

フェーズ 4：セキュリティ — アクセス制御と公開準備

Security タブは公開前の最終ステップです。Data connector が顧客のデータにアクセスまたは表示する前に、顧客が認証されている必要があるかどうかを制御します。

Security タブのスクリーンショット（顧客認証トグルとセキュリティチェックパネルを表示）。

Customer authentication

これをオンにすると、コネクタが機微な情報にアクセスまたは表示する前に、ワークスペースの認証ルールが適用されます。認証ルールは Settings > Workspace > Security > Customer authentication で設定します。

Security check

診断を実行して API セットアップの健全性とセキュリティを評価します。リスクがある場合は実行可能な推奨事項とともに表示されるため、コネクタを公開する前に解決してください。

すべてのセキュリティチェックに合格したら、Save をクリックしてから Set live をクリックします。Data connector のステータスは Settings > Integrations > Data connectors で Live に変わります。Fin は設定されたオーディエンスに一致する会話に対して直ちにそれを使用し始めます。

重要：パラメータ渡しの際に Fin が別の user の情報を誤って共有する可能性がいくつかあります。リスクを最小化するための推奨設定を確認してください。

Data connectors を安全に展開する方法

注意：ここでの Messenger プレビューは例示データを使用しています。Data connector をライブに設定すると、Fin は実際の顧客データを使用します。

Data connectors を Fin が利用するには、ワークフローステップで AI Answers が有効になっている必要があります。AI Answers はテストワークスペースでは有効にできないため、Data connectors は本番環境でのみ完全にテストできます。安全なテストのために本番でテストユーザープロファイルを使用してください。

段階的に Data connectors を顧客基盤に展開するには、audience rules の使用をお勧めします。これにより、Data connector の性能を検証し、必要に応じて調整できます。

Data connectors を監視および管理する方法

既存の Data connectors を見つけるには、Settings > Integrations > Data connectors に移動してください。Data connectors のリストには各コネクタの次の詳細が表示されます：

名前とステータス（live または draft）
一般的な使用状況（合計実行回数）
Fin の使用状況 — 解決率と利用可能なオーディエンス
Health — API success rate と全体的なヘルス指標
Security status
構成の詳細

コネクタ行をクリックすると、そのヘルスダッシュボードが開き、使用状況、パフォーマンス指標、実行ログを確認したり、構成エディタを開いて変更を加えたりできます。

Data connectors リストビューのスクリーンショット（名前、ステータス、一般的使用状況、Fin の使用状況、ヘルス、セキュリティの列があるコネクタ行を表示）。

Inbox で Data connector のアクティビティを表示する方法

特定の会話の Data connector アクティビティを表示するには、Inbox で会話を開き、Show conversation events を選択します。イベントパネルには Fin が Data connector にアクセスしたかどうか、および正常にトリガーされたかどうかが表示されます。

Inbox の会話イベントパネルのスクリーンショット（Data connector トリガーイベントとその成功ステータスを表示）。

注意：

Data connector のトリガーでエラーが発生した場合は、理由を確認するために Logs を選択してください。
他のコンテンツがより関連性が高いと判断された場合、Fin は API リクエストを行っても常に Data connector を使用するとは限りません。
Fin は回答のためにカスタム属性やイベントデータを照会できません。Fin がリアルタイムのアセットデータで応答できるようにするには、Data Connectors を設定して Fin が API 経由で外部データソースにアクセスできるようにしてください。

Inbox views は、「Fin AI Agent: Action used in reply」という属性で作成できます。この属性は Fin が Data connector を呼び出し、応答の一部または全部を回答に使用した場合に設定されます。

Inbox ビューのフィルター設定のスクリーンショット（「Fin AI Agent: Action used in reply」属性がフィルター条件として選択されているのを表示）。

Data connector のバージョン管理

Data connectors は下書き／ライブのバージョン管理システムを使用しているため、実行中のコネクタを中断することなく安全に編集できます。

各 Data connector にはライブ版と下書き版があります。編集は下書きに対して行われ、稼働中のライブ版には影響しません。
下書きを公開すると、新しいバージョンスナップショットが作成されライブ版になります。公開時にメモを追加できます。前のライブ版はアーカイブされます。
各バージョンにはバージョン番号、作成者、変更メモ（追加された場合）、タイムスタンプが記録されます。
変更の完全な履歴は追跡可能で、任意の以前のバージョンにロールバックできます。

注意：これは Fin トリガーの切り替えを含むすべてのコネクタ設定に適用されます。How should Fin use this connector? を変更して公開しない場合、ライブ版はこれまでとまったく同じようにトリガーされ続けます。エディタのバナーは保存されていない変更があることを示します — 変更を有効にするには必ず Set live をクリックしてください。

Public APIs for Data connectors

Two public APIs (application programming interfaces) give you programmatic access to Data connector configurations and execution results. Both use OAuth (Open Authorization) for authentication. Full reference documentation is available in the Intercom Developer Hub.

How to use the Configuration API

The Configuration API is a set of CRUD (create, read, update, delete) endpoints for programmatically managing Data connectors. Use it to create new connectors, keep connectors in sync with your internal systems, and automate connector management at scale. The table below lists the available endpoints and their purpose.

Method	Endpoint	Purpose
GET	/data_connectors	ワークスペース内のすべての Data connector をページネーション付きで返します。更新日時が新しい順に並びます。
GET	/data_connectors/:id	ID によって単一の Data connector の詳細（構成、データ入力、レスポンスフィールド、オブジェクトマッピングを含む）を取得します。
POST	/data_connectors	ドラフト状態で新しい Data connector を作成します。URL、ヘッダー、データ入力、その他の設定を構成し、準備ができたらライブに設定してください。
PATCH	/data_connectors/:id	既存の Data connector を更新します。提供されたフィールドのみが変更されます。コネクタの状態を変更するには state を live または draft に設定してください。
DELETE	/data_connectors/:id	既存の Data connector を削除します。コネクタはドラフト状態であり、任意の workflows または AI agents によって参照されていない必要があります。

認証には OAuth (Open Authorization) を使用します。読み書きアクセスには read_write_data_connectors スコープが必要です。読み取り専用アクセスには read_workflow_connector_execution_result スコープが必要です。

How to use the Results API

The Results API gives you programmatic access to execution data for each Data connector. Use it to build custom dashboards, feed alerting systems, or perform deeper analysis than the in-product health dashboard provides.

GET /data_connectors/:id/execution_results — ページネーションされた実行ログを取得します。デフォルトでは過去1時間の結果が返されます。時間範囲をカスタマイズするには start_ts と end_ts を使用してください。リクエスト/レスポンスボディはデフォルトで除外されます — 含めるには include_bodies=true を使用してください。
GET /data_connectors/:id/execution_results/:result_id — 単一の実行結果を取得します。深いデバッグのために常にリクエスト/レスポンスの完全なボディを含みます。

フィルタリングオプションには成功ステータス、特定のエラータイプ、および Unix タイムスタンプ（1970年1月1日UTCからの経過秒）で指定される時間範囲が含まれます。ページネーションはカーソルベースのモデルを使用し、1ページあたり最大30件の結果を返します。認証には read_workflow_connector_execution_result スコープを使った OAuth を使用します。

既知の制限事項

以下の制限が Data connector に適用されます。回避策が利用可能な場合は、下に記載しています。

Fin は API リクエストが正常に実行されても、常に Data connector を使用するとは限りません — 顧客の質問に対して他のコンテンツがより関連性が高いと判断された場合、代わりにそちらを使用します。回避策はありません。関連性の一致を改善するためにコネクタの名前と説明を見直してください。
Fin は Intercom のカスタム属性やイベントデータを直接クエリして回答することはできません。代わりに Data connector を使用して、このデータを外部の API エンドポイント経由で公開してください。
Data connector を Fin が使用するには、ワークフローステップで AI Answers を有効にする必要があります。AI Answers はテストワークスペースでは有効にできないため、Data connector は本番環境でのみ完全にテストできます。安全なテストには本番でテストユーザープロファイルを使用してください。
Data connector の実行 webhook は、プレビュー会話の一部としてコネクタがトリガーされた場合には発火しません。
Data connector は、ドラフト状態であり、任意の workflows または AI agents から参照されていない場合にのみ API 経由で削除できます。
絵文字は Data connector 名にはサポートされていません — 含めると保存時にエラーが発生します。

注意：顧客が設定できるタイムアウトフィールドはありません。デフォルトのタイムアウトは 15 seconds です。対象ワークスペースで Fin Procedures 内で使用される Data connector の場合、タイムアウトは 30 seconds に延長されます。

Data connectors のトラブルシューティング

Data connector ログの使い方

Fin によってトリガーされた Data connector からのすべてのレスポンスデータは最大14日間記録および保存されます。セキュリティやコンプライアンスのポリシーでより短い期間が必要な場合は、7日間の保持をリクエストするためにサポートチームにお問い合わせください。

ログにアクセスするには、Settings > Integrations > Data connectors に移動し、調査したいコネクタをクリックして、Logs を選択してください。

Data connector の Logs タブのスクリーンショット。タイムスタンプ、ステータス、リクエスト URL、およびレスポンスコードの列がある実行エントリの一覧を表示しています。

Data connector 実行 webhook の使い方

Data connector の成功率と失敗率に関するリアルタイムのシグナルを取得するには、Data connector execution webhook を使用してください。これにより、Intercom から実行イベントを受信し、外部サービスでリアルタイムのダッシュボード、アラート、SLA（サービスレベルアグリーメント）監視を構築できます。