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

注意：データコネクタを作成、編集、またはライブ設定するには、「Can access developer hub」の権限が必要です。

データコネクタはどのように機能しますか？

各データコネクタは、設定するAPI（アプリケーションプログラミングインターフェース）コールで構成されます。Finは自動的に使用タイミングを判断し、顧客固有の回答を提供します。APIを持つ任意のシステムと接続可能で、以下を含みます：

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

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

ヒント：データコネクタは、FinのProceduresやその他の自動化（InboxのWorkflowsやmacroを含む）で使用できます。APIをデータコネクタで設計・使用する方法もご覧ください。

データコネクタの作成方法

設定 > インテグレーション > データコネクタに移動し、新規作成をクリックします。

設定 > インテグレーション > データコネクタのページのスクリーンショット。新規作成ボタンがハイライトされています。

対応アプリがインストールされている場合、データコネクタを作成の下にそのアプリのテンプレートが表示されます。現在、Shopify、Stripe、Statuspageのテンプレートが利用可能です。詳細は下記のサードパーティテンプレートからをご覧ください。

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

以下のアプリがワークスペースにインストールされている場合、データコネクタのテンプレートが利用可能です：

アプリがまだインストールされていない場合は、App Storeでインストールしてください。インストール後、各アプリのデータコネクタテンプレートがデータコネクタとして表示され、ライブ設定可能になります。

テンプレートをクリックすると、データコネクタの機能に関する情報が表示され、Messengerプレビューでテストできます。動作に満足したら、AIエージェント用にライブ設定を選択してください。

データコネクタテンプレートカードのスクリーンショット。MessengerでのFinの応答プレビューと「AIエージェント用にライブ設定」ボタンが表示されています。

ここでのMessengerプレビューはデフォルトで例示データを使用しています。特定のユーザーとしてプレビューし、「トリガー時に実際のユーザーデータにアクセス・更新する」を有効にすると、データコネクタは実際のシステムを呼び出し、そのユーザーの実データを返します。テスト時は必ずテストユーザーアカウントを使用し、実際の顧客は使用しないでください。データコネクタがライブ設定されると、Finはライブ会話で実際の顧客データを使用します。

データコネクタをさらに設定したい場合は、カスタマイズをクリックすると、高度な設定のためのデータコネクタビルダーに移動します。

対応アプリがインストールされていない場合は、ここに表示されるアプリをワークスペースにインストールしてください。インストール後、関連するデータコネクタテンプレートが上記セクションに表示されます。

利用可能なデータコネクタテンプレートとFinのユースケースについて詳しく学びましょう。

AIの推奨から

AI推奨のデータコネクタを見るには、設定 > インテグレーション > データコネクタに移動し、新規データコネクタをクリックします。

「テンプレートからデータコネクタを作成」の下に、あなた専用のAI推奨データコネクタが表示されます。これらは会話履歴に基づいて生成され、潜在的なデータコネクタの特定、解決可能な会話量の割合の確認、Messengerでのプレビューが可能です。設定前に確認できます。

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

AI推奨のデータコネクタをクリックすると、その機能に関する情報が表示され、Messengerでプレビュー（例示データ使用）できます。AI推奨のデータコネクタは会話量に基づく提案であり、動作には手動でAPI接続が必要です。

データコネクタをライブ設定するには、セットアップをクリックしてAPIの詳細を設定します。

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

あとはHTTPS URLを追加してデータコネクタをAPIに接続するだけです。

このデータコネクタをさらにカスタマイズするには、カスタムデータコネクタからのセクションをご覧ください。

ゼロからカスタムデータコネクタを作成する

Fin用のカスタムデータコネクタを設定するには、設定 > インテグレーション > データコネクタに移動し、+ 新規作成 > ゼロから作成をクリックします。

新規データコネクタ画面のスクリーンショット。「ゼロから作成」が選択されており、API、データ、Fin、セキュリティの4段階セットアップタブが表示されています。

フェーズ1：API

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

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

コネクタに短く説明的な名前を付けます。例：「未払いアカウント残高の取得」。これによりFinが使用タイミングを理解します。チームの参考用に内部説明も追加してください。

データコネクタの説明を書く際のベストプラクティスをご覧ください。

注意：データコネクタ名に絵文字はサポートされておらず、含めるとエラーになります。

データ入力

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

+ データ入力をクリックし、フォーマットを選択します。

テキスト
数字
小数点数
真/偽

各入力に名前と説明を付けて、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エンドポイント

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

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

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

重要：エディタは{{...}}のテキストをピルに変換するため、手入力のトークンは有効な属性と見た目が同じになります。識別子が実際の属性（user.idやuser_idなど）に一致しない場合、実行時に空の値となり、リクエストURLが不正になり404エラーなどが発生します。必ずAttribute Inserterのピッカーを使って属性を挿入してください。

認証とヘッダー

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

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

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

注意: 1つのコネクタに複数のトークンを添付できます。各トークンは異なるヘッダーキーを使う必要があり、すべてのトークンがすべてのリクエストに送信されます。

エンドポイントURLと認証情報が完了したら、Test connectionをクリックして設定を検証します。成功すると緑色の確認と生のAPI応答が返ります。失敗するとHTTPエラーコードと説明が表示されます。エラーを解決してからフェーズ2：データに進んでください。

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

フェーズ2：データ — API応答の整形

データタブは、Finが顧客に回答する前にAPI応答をどのようにフィルタリング・変換するかを制御します。Finが見るフィールドを制限し、ビジュアルエディタやPythonコードでデータを整形できます。

Restrict and shape

デフォルトではFinはAPI応答全体にアクセスできます。Finが読める範囲を制限するには、Manually restrict accessに切り替え、公開したいフィールドだけを選択してください。

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

応答の変換方法を選択してください:

テーブルビュー — フィールドをフィルタリング、名前変更、フィールドレベルの変換をビジュアルエディタで設定
Python — Finに届く前に応答をクリーンアップ、整形、再フォーマットするPythonコードを書く

オブジェクトマッピング

オブジェクトマッピングはAPI応答フィールドをIntercomの連絡先や会社属性に直接マッピングし、外部システムからIntercomワークスペースへ自動同期します。

Test codeをクリックしてPython変換ロジックを検証し、Test connectionでAPI呼び出しと応答の形状を確認します。エラーを解決してからフェーズ3：Finに進んでください。

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

フェーズ3：Fin — Finがコネクタをトリガーする方法

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

ヒント：Finがコネクタを使用する前に、以下が整っていることを確認してください:

Data inputs: 検索クエリ、製品名、注文IDなど、FinがAPIに渡す必要がある値には、ソースを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: フェーズ4のセキュリティチェックを完了したら、SaveとSet liveをクリックしてください。

Finはこのコネクタをどのように使いますか？

Enabled (direct trigger)

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

このData connectorを利用できるユーザーは、再利用可能なFinオーディエンスで制御するか、このコネクタ専用のカスタムオーディエンスを作成して設定できます。例えば、「Enterprise plan」オーディエンスの顧客に利用可能にしたり、ログイン済みでメール認証済みのユーザーでアカウント残高について質問するカスタムオーディエンスに限定したりできます。

注意：現在、FinオーディエンスをData connectorsで使用できます。Finオーディエンスは一度作成すれば複数のコネクタで使い回せる顧客グループで、一貫性を保ちやすくなります。

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

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

Disabled (manual trigger)

コネクタは自動で実行されません。Workflow、Procedure、またはMacroに手動で追加する必要があります。これは「Delete account」のような、実行前に人間やworkflowの監視が必要な、機密性や書き込み操作があるコネクタに最適です。

Finプレビューを使って、このコネクタを使ったFinの応答をライブ設定前に正確に確認できます。

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

フェーズ4：セキュリティ — アクセス制御とライブ化

セキュリティタブはライブ化前の最終ステップです。Data connectorが顧客のデータにアクセスまたは表示する前に認証が必要かどうかを制御します。

顧客認証

このスイッチをオンにすると、コネクタが機密情報にアクセスまたは表示する前に、ワークスペースの認証ルールが適用されます。認証ルールは設定 > ワークスペース > セキュリティ > 顧客認証で構成します。

セキュリティチェック

API設定の健全性とセキュリティを診断します。リスクがあれば実行可能な推奨事項とともに表示されるので、ライブ化前に解決してください。

すべてのセキュリティチェックに合格したら、保存をクリックし、続けてSet liveをクリックします。Data connectorのステータスは設定 > 統合 > Data connectorsでLiveに変わります。Finは設定されたオーディエンスに合致する会話で即座に使用を開始します。

重要：パラメータ渡し時にFinが別のユーザーの情報を誤って共有する可能性がいくつかあります。リスク軽減のための推奨設定はこちらをご覧ください。

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

注意：ここでのMessengerプレビューはデフォルトで例示データを使用します。特定ユーザーとしてプレビューし、「トリガー時に実際のユーザーデータにアクセス・更新」を有効にすると、Data connectorは実際のシステムを呼び出し、そのユーザーの実データを返します。テスト時は必ずテストユーザーアカウントを使い、実際の顧客は使わないでください。Data connectorがライブ設定されると、Finはライブ会話で実際の顧客データを使用します。

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

オーディエンスルールを使ってData connectorsを段階的に顧客基盤に展開することを推奨します。これによりData connectorのパフォーマンスを検証し、必要に応じて調整や変更が可能になります。

Data connectorsの監視と管理方法

既存のData connectorsを見つけるには、設定 > 統合 > Data connectorsに移動します。Data connectorsリストには各コネクタの以下の詳細が表示されます。

名前とステータス（ライブまたはドラフト）
一般的な使用状況（総実行回数）
Finの使用状況 — 解決率と利用可能なオーディエンス
健全性 — API成功率と全体的な健全性指標
セキュリティステータス
設定詳細
複製オプション — 新しいコネクタの出発点としてコピーを作成

コネクタの行をクリックすると、使用状況、パフォーマンス指標、実行ログを確認できるヘルスダッシュボードが開き、設定エディタで変更も可能です。

名前、ステータス、一般使用状況、Fin使用状況、健全性、セキュリティの列があるData connectorsリストビューのスクリーンショット。

InboxでData connectorのアクティビティを見る方法

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

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

注意：

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を呼び出し、回答に一部または全部の応答を使用した場合に設定されます。

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

Data connectorのバージョニング

Data connectorsはドラフト/ライブのバージョニングシステムを使用しており、実行中のコネクタを中断せずに安全に編集できます。

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

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

データコネクターのパブリックAPI

2つのパブリックAPI（アプリケーションプログラミングインターフェース）により、Data connectorの設定と実行結果にプログラム的にアクセスできます。両方とも認証にOAuth（Open Authorization）を使用します。完全なリファレンスドキュメントはIntercom Developer Hubで利用可能です。

Configuration APIの使い方

Configuration APIは、Data connectorをプログラム的に管理するためのCRUD（作成、読み取り、更新、削除）エンドポイントのセットです。新しいコネクターの作成、内部システムとの同期維持、大規模なコネクター管理の自動化に使用します。以下の表は利用可能なエンドポイントとその目的を示しています。

メソッド	エンドポイント	目的
GET	/data_connectors	ワークスペース内のすべてのData connectorのページネーションされたリストを、更新日時の新しい順に返します。
GET	/data_connectors/:id	IDで単一のData connectorの詳細を取得します。設定、データ入力、応答フィールド、オブジェクトマッピングを含みます。
POST	/data_connectors	ドラフト状態の新しいData connectorを作成します。URL、ヘッダー、データ入力、その他の設定を構成し、準備ができたらライブに設定します。
PATCH	/data_connectors/:id	既存のData connectorを更新します。提供されたフィールドのみが変更されます。状態をライブまたはドラフトに設定してコネクターの状態を変更します。
DELETE	/data_connectors/:id	既存のData connectorを削除します。コネクターはドラフト状態であり、いかなるworkflowsやAI agentsにも使用されていない必要があります。

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

Results APIの使い方

Results APIは各Data connectorの実行データにプログラム的にアクセスできます。カスタムダッシュボードの構築、アラートシステムへのフィード、製品内ヘルスダッシュボードより深い分析に使用します。

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が使用するには、workflowステップでAI Answersを有効にする必要があります。AI Answersはテストワークスペースでは有効にできないため、Data connectorは本番環境でのみ完全にテスト可能です。安全なテストには本番環境のテストユーザープロファイルを使用してください。
Data connector実行webhookは、プレビュー会話の一部としてコネクターがトリガーされた場合には発火しません。
Data connectorはドラフト状態であり、いかなるworkflowsやAI agentsにも参照されていない場合にのみAPI経由で削除できます。
Data connector名に絵文字はサポートされていません。含めると保存時にエラーになります。
担当者のメールアドレスはData connectorリクエストのプレースホルダーとして公開されていません。利用可能なのは担当者ID（admin_assignee_id）のみです。担当者のメールを取得するには、admin_assignee_idを渡してAdmins API（GET /admins/{admin_id}）で対応するレコードを参照し、emailフィールドを取得してください。あるいは、割り当て時にカスタム会話属性にメールを保存し、その属性を参照してください。

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

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

Data connectorログの使い方

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

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

Data connectorのLogsタブのスクリーンショット。タイムスタンプ、ステータス、リクエストURL、レスポンスコードの列がある実行エントリーのリストを表示。

Data connector実行webhookの使い方

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