メインコンテンツにスキップ

Finのためのデータコネクタを作成する

外部システムからのデータを必要とするパーソナライズされた回答でFinを設定する方法。

各データコネクタは、裏で設定可能なAPIコールで構成されます。Finは自動的に使用タイミングを選び、顧客にパーソナライズされた回答を提供します。

APIを持つ任意のシステムを接続できます。これは、ビジネスのために構築した独自の内部バックエンドツールや、Shopify、Salesforce、Stripe、Jiraなどのサードパーティアプリかもしれません。

注意：

データコネクタを作成する

Finのカスタムデータコネクタを設定するには、設定 > 統合 > データコネクタに移動し、+ 新規をクリックします。

フェーズ1：API

設定エディタはAPI、Data、Fin、Securityの4つのタブで構成されています。ライブ設定前に各タブを順に進めてコネクタを構築してください。

識別

まず、このデータコネクタが何をするかを説明する短い名前（例：「未払いのアカウント残高を取得」）を入力します。次に、Finが使用すべきタイミングを説明する詳細な説明を入力します。

このデータコネクタが提供するデータの例や、顧客の問い合わせ例を含めてください。

例えば：

このデータコネクタは顧客の最近の取引を取得します。このデータコネクタは重要な情報を提供します。例として顧客の問い合わせには… 「アカウントに未払い残高があるか確認できますか？」「今、支払いが必要なものはありますか？」「アカウントに未払いはありますか？」「未払いの請求書や料金があるか教えてください」「アカウントに清算すべき残高はありますか？」「アカウントが完全に支払われているか確認できますか？」

API接続

必要に応じて、Finがこのデータコネクタを使用する前にデータを収集すべきか指定できます。これは、データコネクタ実行前にデータの存在を確認したい場合に役立ちます。例えば、Intercomのユーザープロフィールにアカウント番号が保存されていない場合、顧客にアカウント番号を尋ねることが考えられます。

データ入力を収集するには、＋ データ入力を追加をクリックし、収集すべきデータの形式（テキスト、数値、小数、真偽値）を選択し、名前と説明を付けてFinが収集方法を理解できるようにします。

注意：

  • 利用可能な場合、Finは会話のコンテキストから情報を収集します。

  • XMLを返すAPIにもデータコネクタを接続できます。IntercomはXMLレスポンスを自動的にJSONに変換するため、手動変換やサードパーティツールは不要です。これにより、JSON非対応の外部システムにも接続可能です。

次に、APIのHTTPS URLを指定し、リクエストメソッド（GET、POST、PUT、DELETE、PATCH）を選択します。

顧客のユーザーIDやメールなど、ワークスペース内の属性を使って検索を行うこともあります。また、正しい認証トークンと正しいヘッダー（例：Accept: application/jsonやContent-Type: application/json）を指定する必要があります。

設定が完了したら、接続をテストしてからDataタブに進んでください。

レスポンステスト

このアクションが接続先APIから正しいデータを取得しているかテストする必要があります。テスト方法は2つあります：

  1. ライブレスポンス：APIリクエストからのライブレスポンスデータでテストし、設定が正しいか確認します。ライブレスポンスは実際にAPIコールを行うため、実データに影響が出る可能性があるので注意してください。

  2. 例示レスポンス：APIがまだ完全に開発されていない場合や特定のレスポンスをシミュレート/モックする必要がある場合に有用なJSONデータを提供します。

問題なければ、Dataタブに進みレスポンスの形状を設定してください。

フェーズ2：Data

このタブは、Finが使用する前にAPIレスポンスの形状を制御します。

制限と形状設定

デフォルトでは、Finは返信生成のために全レスポンスデータにアクセスできます。アクセス制限したい場合は手動でアクセス制限を選択し、Finにアクセスを許可するデータフィールドをチェックしてください。

個々のデータ項目は編集アイコンをクリックして、顧客向けの名前を付けたり、データの変換を指定したりできます。

例えば、APIレスポンスが残高0を返す場合、Finが未払い残高は0と答える代わりに、現在未払い残高はないと回答できます。

コードを使ってレスポンスをフィルタまたは変換する

データコネクタのコードブロックでは、Pythonを使ってAPIレスポンスを直接変換・操作できます。コネクタ設定内で行えます。

APIからの非構造化または大容量ペイロードは、FinなどのAIベースの応答が誤認や誤解、明確な回答の失敗を引き起こすことがあります。これを防ぐため、バックエンド変更やサードパーティ統合なしに、APIレスポンスをプログラム的に前処理、フィルタリング、調整できます。

仕組み

  • return文：コードブロックの主な結果は必ずreturn文で返す必要があります。返されたものだけがFinやコネクタの他部分に送られます。

  • print()文：デバッグや進捗ログ用にのみ使用してください。これらの出力は別途キャプチャされ、API結果としては送信されません。

  • 標準モジュールのみ：使用できるのは標準Pythonモジュール（math、decimal、re、datetime、datetime.timezone、json、random、time）に限定されます。必要に応じて追加予定です。

注意：

  • 非JSONテストレスポンス：コードブロックはAPIテストレスポンスが有効なJSONオブジェクトまたは配列であることを要求します。非JSONペイロードはサポートされず（失敗の原因となります）。

  • 非成功APIリクエスト：コードブロックは成功したAPIレスポンス（ステータスコード200）のみ変換可能です。400、404、500などのエラーコードレスポンスは変換対象外です。

データコネクタのコードブロック設定方法

設定 > 統合 > データコネクタに移動し、コードブロックを使いたいデータコネクタを選択します。次にデータ変換をクリックし、「コードを使ってレスポンスをフィルタまたは変換する」オプションを選択します。

コードブロック内で入力データ（APIレスポンス）にアクセスする

APIから返されたデータ（テストレスポンス）にアクセスするには、コードブロック内でinputs['data']変数を使用します。通常、APIの全レスポンスを取得し、自由に変換できます。

例えば、コードブロックの冒頭で通常は次のように書きます：

api_response = inputs['data']

これはAPIレスポンス（APIによってPythonの辞書、リスト、または文字列）を変数api_responseに割り当て、さらに処理を行います。

コードブロックの自動提案を取得する

Data transformationタブに移動すると、データコネクターの応答が自動的に分析され、Finのパフォーマンスを向上させる提案が特定されます。

これはUnixタイムスタンプや過大なペイロードなどの一般的な問題を検出します。これらは非構造化または過剰に大きなデータで、AIベースの応答が幻覚を起こしたり、誤解したり、明確な回答を提供できなくなる原因となります。

提案が見つかると、View suggestionボタン付きのバナーが表示され、Finのためにデータをよりクリーンで信頼性の高いものにする推奨Pythonコードが示されます。Test codeを選択して結果を確認してください。

返却文に満足したら、Accept suggestionを選択して、コネクターデータからのFinの応答の品質と精度を大幅に向上させます。

ヒント： データ変換のためのこれらのヒントと実用例をチェックしてください。

オブジェクトマッピング

Fin用のデータコネクターを作成する際、応答データをIntercomの属性やオブジェクトにマッピングする必要はありません。代わりに、FinはJSON応答を直接解釈し、それを使って質問に答えます。応答は「Test response」セクションに基づいて生成されます。各行項目はJSON応答のデータポイントに対応しています。

Dataタブの設定が完了したら、Phase 3: FinでFinがこのコネクターをどのように使用するかを定義し、Phase 4: Securityで認証を設定し、ライブ前にセキュリティチェックを実行します。

Phase 3: Fin

このタブはFinがコネクターとどのように連携するかを決定します。

Finはこのコネクターをどのように使用すべきですか？

2つのモードから選択してください：

  • Enabled (direct trigger) — Finは顧客の質問に基づいて自動的にコネクターをトリガーします。読み取り専用のコネクター（「Check order status」など）や大量の繰り返しクエリに最適です。

  • Disabled (manual trigger) — コネクターは自動的に実行されません。Workflow、Task、Procedure、またはMacroに手動で追加する必要があります。実行前に人間やワークフローの監視が必要な機密性の高い書き込みアクティブなコネクターに最適です。

対象者

再利用可能なFinのaudiencesを使ってこのコネクターの利用可能者を制御するか、一時的なルール用にカスタムaudienceを作成します。例えば、「Enterprise plan」audienceの顧客に利用可能にしたり、認証済みメールを持つログインユーザーに制限したりできます。

ヒント： Everyone、再利用可能なFin audience、または一時的なルール用のCustomaudienceを選択できます。複数のFin audiencesを選択できますが、CustomルールとFin audienceを組み合わせることはできません。既存のaudienceルールは機能を維持するためにCustomaudienceになります。

Finプレビュー

Finプレビューを使って、このコネクターをライブにする前にFinがどのように応答するかを正確に確認できます。

Phase 4: Security

ライブ前の最終ステップ。このタブは顧客データのアクセス制御を扱います。

顧客認証

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

セキュリティチェック

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

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

すべてのチェックが通ったら、コネクターを保存してライブに設定してください。

データコネクターの展開

audienceルールを使って、顧客ベースに段階的にデータコネクターを展開することを推奨します。これにより、データコネクターのパフォーマンスを検証し、必要に応じて調整や変更が可能になります。

データコネクターがユーザーに対してトリガーされない問題がある場合は、テスト段階で追加した会社固有のaudienceルールを削除していることを確認してください。

トラブルシューティング

トラブルシューティングのため、Finがトリガーしたデータコネクターによって生成されたすべての応答データは最大14日間記録されます。これらのログはData Connector > Logsタブでアクセスできます。Finがアクセスできるデータの種類に基づいて応答データを表示できます。

  • 全応答 – 完全で未修正の応答

  • 編集済み＆フォーマット済み応答 – 変換後

  • 応答データなし

よくある質問

Finの会話をZendeskやSalesforce以外のサードパーティプラットフォームに引き継ぐ際に、Data connectorsを使って属性を送信できますか？

POSTリクエスト（例：以下のような構造）を送信しようとしている場合は、代わりにFinのworkflow handoffオプションを使用してください：

{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}

Workflow handoffオプションには、JavaScriptによるハンドオフとURLへのハンドオフが含まれ、AI生成の要約を通じて会話のコンテキストを含めることができます。

1. JavaScriptによるハンドオフ

これにより、Messengerアプリでhandoff_with_javascript関数を定義でき、以下が可能になります：

  • 会話の要約を収集（“AI Add Summary Note”経由）

  • ユーザーのメールにアクセス（属性を使用）

  • fetch()またはXMLHttpRequestを使って、希望する構造で外部エンドポイントに送信

詳細はこちら 👉 JavaScriptによるハンドオフ

2. URLへのハンドオフ

このオプションはユーザーを特定のページにリダイレクトするだけで、POSTを送信したり会話データを運んだりはしません。したがって、JSONをPOSTしようとしている場合には適していません。

推奨設定

JavaScript hand-off を使用し、次のようなロジックを含めてください:

handoff_with_javascript = function (params) {
const userEmail = params.user.email;
const summary = params.conversation_summary;

fetch('https://your-endpoint.com/api', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
body: summary,
from: userEmail,
to: 'your_support@company.com'
})
});
}

関連記事
Finのオーディエンスとターゲティングを管理する
人気のあるアプリやカスタムMCP用のMCPコネクタを追加する
認証トークンとAPIトークンの作成
Finの手順とデータコネクタの説明
Fin Proceduresでのデータコネクタの使い方
こちらの回答で解決しましたか？