この記事では、Finが外部システムからライブデータを取得し、チームメイトを待たずに顧客にパーソナライズされた回答を提供できる機能であるデータコネクタの設定、構成、管理方法を説明します。テンプレートまたはゼロからコネクタを作成し、APIエンドポイントを設定し、レスポンスを整形し、トリガー可能なユーザーを制御し、セキュリティを管理し、安全に展開し、パフォーマンスを監視する方法を学びます。
注意：データコネクタを作成、編集、またはライブ設定するには、「Can access developer hub」の権限が必要です。
データコネクタはどのように機能しますか？
各データコネクタは、設定するAPI（アプリケーションプログラミングインターフェース）コールで構成されます。Finは顧客固有の回答を提供するためにいつ使用するかを自動的に判断します。APIを持つ任意のシステムと接続できます。例として：
カスタム内部バックエンドツール
サードパーティプラットフォーム（Shopify、Salesforce、Stripe、Jiraなど）
ヒント：データコネクタは、FinのProceduresやその他の自動化、InboxのWorkflowsやmacroでも使用できます。APIをデータコネクタで設計・使用する方法について詳しく学びましょう。
データコネクタの作成方法
設定 > インテグレーション > データコネクタに移動し、新規作成をクリックします。
対応アプリがインストールされている場合、データコネクタを作成の下にそのアプリのテンプレートが表示されます。現在、Shopify、Stripe、Statuspageのテンプレートが利用可能です。詳細は下記のサードパーティテンプレートからをご覧ください。
サードパーティテンプレートから
次のアプリがワークスペースにインストールされている場合、データコネクタのテンプレートが利用可能です：
テンプレートをクリックすると、データコネクタの機能に関する情報が表示され、Messengerプレビューでテストできます。動作に満足したら、AIエージェント用にライブ設定を選択してください。
ここでのMessengerプレビューは例示データを使用しています。データコネクタをライブ設定すると、Finは実際の顧客データを使用します。
データコネクタを構成したい場合は、カスタマイズをクリックすると、高度な設定のためのデータコネクタビルダーに移動します。
対応アプリがインストールされていない場合は、ここに表示されるアプリをワークスペースにインストールしてください。インストール後、関連するデータコネクタテンプレートが上記のセクションに表示されます。
利用可能なデータコネクタテンプレートとFinのユースケースについて詳しく学びましょう。
AIの推奨から
AI推奨のデータコネクタを見るには、設定 > インテグレーション > データコネクタに移動し、新規データコネクタをクリックします。
「テンプレートからデータコネクタを作成」の下に、あなた専用のAI推奨データコネクタが表示されます。これらは会話履歴に基づいて生成され、潜在的なデータコネクタの特定、解決可能な会話量の割合の確認、Messengerでのプレビューが可能です。設定前に確認できます。
AI推奨が表示されるには、Finがワークスペースでライブ稼働しており、十分な会話量が必要です。
AI推奨データコネクタをクリックすると、その機能に関する情報が表示され、Messengerでプレビュー（例示データ使用）できます。AI推奨データコネクタは会話量に基づく提案に過ぎず、動作には手動でAPI接続が必要です。
データコネクタをライブ設定するには、セットアップをクリックしてAPIの詳細を構成します。
あとはHTTPS URLを追加してデータコネクタをAPIに接続するだけです。
このデータコネクタをさらにカスタマイズするには、カスタムデータコネクタからのセクションを参照してください。
ゼロからカスタムデータコネクタを作成する
Fin用のカスタムデータコネクタを設定するには、設定 > インテグレーション > データコネクタに移動し、+ 新規作成 > + ゼロから作成をクリックします。
フェーズ1：API
APIタブは、Intercomが外部システムと通信する方法を定義します。
コネクタに短く説明的な名前を付けます。例：「未払いのアカウント残高を取得」。これにより、Finが使用タイミングを理解しやすくなります。チームの参考のために内部説明も追加してください。
データコネクタの説明を書く際のベストプラクティスを参照してください。
注意：データコネクタ名に絵文字はサポートされておらず、含めるとエラーになります。
データ入力
データ入力では、コネクタが実行される前にFinが収集する必要がある情報を指定できます。例えば、Intercomにまだ保存されていない顧客のアカウント番号などです。
+ データ入力をクリックし、フォーマットを選択します：
テキスト
数字
小数点数値
真/偽
各入力に名前と説明を付けて、Finがどのように収集するかを認識できるようにします。APIがnullまたは応答が欠落している場合のフォールバック値も設定できます。
各入力について、データの取得元を選択してください：
Let Fin collect — Finが会話から自動的に収集します
People attribute — 既存のIntercom属性から取得
Custom value — あなたが定義する固定値
APIエンドポイント
APIエンドポイントのHTTPS（セキュアウェブ）URLを追加し、HTTPリクエストメソッドを選択してください：GET（データ取得）、POST（データ送信）、PUT（データ置換）、DELETE（データ削除）、またはPATCH（一部更新）。
Attribute Inserterを使って、顧客のuser IDのような動的な値をURLパスやリクエストボディに直接渡します。
認証とヘッダー
認証トークンを選択し、APIが必要とするカスタムのキーと値のヘッダーを追加してください（例：Content-Type: application/json）。
注意：1つのコネクタに複数のトークンを添付できます。各トークンは異なるヘッダーキーを使用する必要があり、すべてのトークンがすべてのリクエストに送信されます。
エンドポイントURLと認証情報が完了したら、Test connectionをクリックして設定を検証します。成功すると緑色の確認と生のAPI応答が返されます。失敗するとHTTPエラーコードと説明が表示されます。エラーを解決してからフェーズ2：データに進んでください。
フェーズ2：データ — API応答の整形
Dataタブは、Finが顧客に回答する前にAPI応答をどのようにフィルタリングおよび変換するかを制御します。Finが見るフィールドを制限し、ビジュアルエディターやPythonコードでデータを整形できます。
制限と整形
デフォルトでは、FinはAPI応答全体にアクセスできます。Finが読める内容を制限するには、手動でアクセス制限に切り替え、公開したいフィールドのみを選択してください。
応答をどのように変換するか選択してください：
テーブルビュー — フィールドをフィルタリングし、名前を変更し、フィールドレベルの変換をビジュアルエディターで設定
Python — Finに届く前に応答をクリーンアップ、整形、再フォーマットするPythonコードを書く
オブジェクトマッピング
オブジェクトマッピングでは、API応答フィールドをIntercomの連絡先または会社属性に直接マッピングし、外部システムからIntercomワークスペースへのデータ同期を自動化します。
Test codeをクリックしてPython変換ロジックを検証し、Test connectionでAPI呼び出しと応答の形状を確認します。エラーを解決してからフェーズ3：Finに進んでください。
フェーズ3：Fin — Finがコネクタをトリガーする方法
Finタブは、FinがDataコネクタを自動的にトリガーするか、ワークフロー、手順、またはmacroから明示的に呼び出されたときのみトリガーするかを制御します。コネクタの感度や書き込みアクティブ度に合ったトリガーモードを選択してください。
Finはこのコネクタをどのように使用すべきですか？
有効（直接トリガー）
Finは顧客の質問に基づいてコネクタを自動的にトリガーします。ワークフローは不要です。読み取り専用のコネクタ（「注文状況の確認」など）や大量の繰り返しクエリに最適です。
このDataコネクタを利用できるユーザーは、再利用可能なFinオーディエンスや、このコネクタ専用のカスタムオーディエンスを作成して制御できます。例えば、「Enterprise plan」オーディエンスの顧客に提供したり、ログイン済みでメール認証済みのユーザーでアカウント残高について質問する人に限定したりできます。
注意：現在、FinオーディエンスをDataコネクタで使用できます。Finオーディエンスは一度作成して複数のコネクタで使い回せる顧客グループで、一貫性を保ちやすくなります。
全員、再利用可能なFinオーディエンス、または一時的なカスタムオーディエンスを選択できます。
複数のFinオーディエンスを選択できますが、カスタムルールとFinオーディエンスを組み合わせることはできません。
既存のDataコネクタのオーディエンスルールは、機能を維持するためにカスタムオーディエンスになります。
ヒント：Dataコネクタを顧客に有効化する前にテストしたい場合は、オーディエンスルールを使って最初は自分やチームメンバーだけにDataコネクタを有効にしてください。
無効（手動トリガー）
コネクタは自動的に実行されません。Workflow、Procedure、またはMacroに手動で追加する必要があります。書き込みアクティブなコネクタ（「アカウント削除」など）や、実行前に人間やワークフローの監視が必要な場合に最適です。
Finプレビューを使って、このコネクタをライブにする前にFinがどのように応答するか正確に確認してください。
フェーズ4：セキュリティ — アクセス制御とライブ化
Securityタブはライブ化前の最終ステップです。顧客がDataコネクタにアクセスまたはデータ表示する前に認証が必要かどうかを制御します。
顧客認証
このスイッチをオンにして、コネクタが機密情報にアクセスまたは表示する前にワークスペースの認証ルールを適用してください。認証ルールは設定 > ワークスペース > セキュリティ > 顧客認証で構成します。
セキュリティチェック
API設定の健全性とセキュリティを評価するために診断を実行します。リスクがあれば実行可能な推奨事項とともに表示されます。コネクタをライブに設定する前に解決してください。
すべてのセキュリティチェックに合格したら、保存をクリックし、次にライブ設定をクリックします。データコネクタのステータスは設定 > 統合 > データコネクタでライブに変わります。Finは設定された対象に一致する会話で直ちに使用を開始します。
重要: パラメータ渡し時にFinが他のユーザーの情報を誤って共有する可能性がいくつかあります。リスクを最小限に抑えるための推奨設定はこちら。
データコネクタを安全に展開する方法
注意: ここでのMessengerプレビューは例示データを使用しています。データコネクタをライブ設定すると、Finは実際の顧客データを使用します。
データコネクタは、Finが使用するためにworkflowステップでAI Answersを有効にする必要があります。AI Answersはテストワークスペースでは有効にできないため、データコネクタは本番環境でのみ完全にテスト可能です。安全なテストのために本番環境でテストユーザープロファイルを使用してください。
データコネクタを段階的に顧客ベースに展開するには、audience rulesの使用を推奨します。これにより、データコネクタのパフォーマンスを検証し、必要に応じて調整や変更が可能になります。
データコネクタの監視と管理方法
既存のデータコネクタを見つけるには、設定 > 統合 > データコネクタに移動します。データコネクタリストには各コネクタの以下の詳細が表示されます。
名前とステータス（ライブまたはドラフト）
一般的な使用状況（総実行回数）
Finの使用状況 — 解決率と利用可能な対象
健全性 — API成功率と全体的な健全性指標
セキュリティステータス
設定の詳細
コネクタの行をクリックすると、その健全性ダッシュボードが開き、使用状況、パフォーマンス指標、実行ログを確認したり、設定エディタを開いて変更を加えたりできます。
Inboxでのデータコネクタのアクティビティの確認方法
特定の会話のデータコネクタのアクティビティを確認するには、Inboxで会話を開き、会話イベントを表示を選択します。イベントパネルにはFinがデータコネクタにアクセスしたかどうか、正常にトリガーされたかが表示されます。
注意:
データコネクタのトリガーにエラーがある場合は、ログを選択して原因を確認してください。
FinはAPIリクエストを行っても、他のコンテンツがより関連性が高いと判断した場合はデータコネクタを使用しないことがあります。
Finはカスタム属性やイベントデータをクエリして回答することはできません。Finがリアルタイムの資産データで応答できるようにするには、API経由で外部データソースにアクセスできるようにData Connectorsを設定してください。
Inbox viewsは「Fin AI Agent: Action used in reply」という属性で作成できます。この属性はFinがData connectorを呼び出し、回答に一部または全部の応答を使用した場合に設定されます。
データコネクタのバージョニング
データコネクタはドラフト/ライブのバージョニングシステムを使用しており、実行中のコネクタを中断せずに安全に編集できます。
各データコネクタにはライブバージョンとドラフトバージョンがあります。編集はドラフトに対して行われ、実行中のライブバージョンには影響しません。
ドラフトを公開すると、新しいバージョンスナップショットが作成され、ライブバージョンになります。公開時にメモを追加できます。以前のライブバージョンはアーカイブされます。
各バージョンはバージョン番号、作成者、変更メモ（追加された場合）、タイムスタンプを記録します。
変更の全履歴が追跡可能で、任意の以前のバージョンにロールバックできます。
Data connectorsの公開API
2つの公開API（アプリケーションプログラミングインターフェース）により、Data connectorの設定と実行結果にプログラム的にアクセスできます。両方とも認証にOAuth（Open Authorization）を使用します。完全なリファレンスドキュメントはIntercom Developer Hubで利用可能です。
Configuration APIの使い方
Configuration APIはData connectorsをプログラム的に管理するためのCRUD（作成、読み取り、更新、削除）エンドポイントのセットです。新しいコネクタの作成、内部システムとの同期、スケールでのコネクタ管理の自動化に使用します。以下の表は利用可能なエンドポイントとその目的を示しています。
メソッド | エンドポイント | 目的 |
GET | /data_connectors | ワークスペースのすべてのData connectorsのページネーションされたリストを返します。更新日時の新しい順に並びます。 |
GET | /data_connectors/:id | IDで単一のData connectorの詳細を取得します。設定、データ入力、応答フィールド、オブジェクトマッピングを含みます。 |
POST | /data_connectors | ドラフト状態で新しいData connectorを作成します。URL、ヘッダー、データ入力、その他の設定を構成し、準備ができたらライブに設定します。 |
PATCH | /data_connectors/:id | 既存のData connectorを更新します。提供されたフィールドのみが変更されます。コネクタの状態をliveまたはdraftに設定して状態を変更してください。 |
削除 | /data_connectors/:id | 既存のData connectorを削除します。コネクタはdraft状態であり、いかなる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件の結果を返します。認証はOAuthでread_workflow_connector_execution_resultスコープを使用します。
既知の制限事項
以下の制限は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はdraft状態であり、いかなるworkflowsやAIエージェントからも参照されていない場合にのみAPI経由で削除可能です。
Data connector名に絵文字はサポートされていません。含めると保存時にエラーが発生します。
Data connectorのトラブルシューティング
Data connectorログの使い方
FinによってトリガーされたData connectorのすべてのレスポンスデータは記録され、最大14日間保存されます。ログにアクセスするには、設定 > Integrations > Data connectorsに移動し、調査したいコネクタをクリックしてLogsを選択してください。
Data connector実行webhookの使い方
Data connectorの成功率と失敗率のリアルタイム信号にはData connector execution webhookを使用してください。これによりIntercomから実行イベントを受信し、外部サービスでリアルタイムダッシュボード、アラート、SLA（サービスレベルアグリーメント）監視を構築できます。
注意：
Data connector通知を受け取るには、アプリを作成し、Webhooksを設定し、Data connector実行webhookを購読する必要があります。
Data connectorがプレビュー会話の一部としてトリガーされた場合、Data connector実行webhookはスキップされます。