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

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

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

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

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

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

ヒント：データコネクタは、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を使って、顧客のusers IDのような動的値をURLパスやリクエストボディに直接渡します。トークンは必ずピッカーで選択し、手動で入力しないでください。

注意：コネクタがIntercom Contacts APIを呼び出し、連絡先を識別する必要がある場合は、ピッカーからContact ID（user.id）を選択してください。User ID（user_id）ではありません。Contacts APIはIntercom生成の連絡先ID（user.id）を期待しています。user_id（外部設定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を使う場合、名前に括弧()、プラス記号+、スラッシュ/などの特殊文字を含むフィールドは、path matching bugのためFinが受け取るデータから静かに除外されることがあります。回避策として、アクセス制限前に対象フィールドの特殊文字を削除して名前を変更してください。あるいは、応答に機密データが含まれない場合は全データアクセスを使用してください。

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

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

オブジェクトマッピング

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

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

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

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

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

ヒント：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: フェーズ4のセキュリティチェックを完了したら、SaveとSet liveをクリックしてください。

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

Enabled (direct trigger)

Finは顧客の質問に基づいてコネクタを自動的にトリガーします。workflowは不要です。「注文状況の確認」などの読み取り専用コネクタや、高頻度で繰り返し行われる問い合わせに最適です。

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

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

Everyone、再利用可能なFin audience、または一時的なルール用の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：セキュリティ — アクセス制御とライブ化

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

顧客認証

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

セキュリティチェック

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

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

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

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

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

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

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

Data connectorsの監視と管理方法

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

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

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

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

2つのPublic APIs（アプリケーションプログラミングインターフェース）により、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エージェントにも使用されていない必要があります。

認証には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エージェントにも参照されていない場合にのみAPI経由で削除できます。
Data connector名に絵文字はサポートされていません。含めると保存時にエラーが発生します。

注意：顧客が設定可能なタイムアウトフィールドはありません。デフォルトのタイムアウトは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（サービスレベルアグリーメント）監視を構築できます。