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

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：データ

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

制限と形状設定

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

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

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

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

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

データコネクタのコードブロックでは、Pythonを使ってAPIレスポンスを直接変換・操作できる機能を提供しています。

APIからの非構造化または過大なペイロードは、Finや他のAIエージェントのような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の対象者を使ってこのコネクタの利用可能なユーザーを制御するか、一時的なルール用にカスタム対象者を作成します。例えば、「Enterprise plan」対象者の顧客に利用可能にしたり、認証済みメールのログインユーザーに制限したりします。

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

Finプレビュー

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

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

Phase 4: Security

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

顧客認証

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

セキュリティチェック

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

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

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

注意： データコネクタはドラフト/ライブのバージョン管理システムを使用しています。FinタブのFinトリガー設定を含む変更はドラフトとして保存され、Set liveをクリックするまでライブコネクタに反映されません。変更後にコネクタの動作がおかしい場合は、更新されたドラフトが公開されているか確認してください。設定の一覧は設定画面で各コネクタの現在の状態（ライブまたはドラフト）を表示します。

データコネクタの展開

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

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

ヒント： 既存のデータコネクタを複製して新しいコネクタの出発点として使えます。コネクタを開き、右上の...メニューをクリックしてDuplicateを選択してください。コピーはドラフトモードで開き、すべての設定が事前に入力されています。

トラブルシューティング

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

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

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

  • 応答データなし

よくある質問

Finの会話をサードパーティプラットフォーム（Zendesk/Salesforce以外）に引き継ぐ際に、属性を送信するためにデータコネクタを使用できますか？

POSTリクエスト（例えば以下のような構造）を送信しようとしている場合は、代わりにFinのワークフローハンドオフオプションを使用してください:

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

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

1. JavaScriptによるハンドオフ

これにより、Messengerアプリでhandoff_with_javascript関数を定義でき、次のことが可能になります:

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

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

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

詳細はこちら 👉 Hand-off with 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'
})
});
}

こちらの回答で解決しましたか？

関連記事