データコネクタは、サードパーティシステムのデータに接続してパーソナライズされた回答を提供する強力な方法です。顧客がチームメイトの手動検索を待ったり、自分で情報を探す代わりに、Finが関連データに即座にアクセスし、個別の返信を作成します。
これらのデータコネクタが正しく機能し、適切なシナリオで使用されるように、以下のベストプラクティスを考慮してください。
効果的なデータコネクタのプロンプトを書く
最も重要なステップの一つは、データコネクタのFinセクションで効果的なプロンプトを書くことです。
Fin AI Agentがこのデータコネクタを起動すべき状況を説明するために、3～5文を書いてください。できるだけ具体的にし、以下のいずれかを必ず含めてください。
このデータコネクタで回答される顧客の問い合わせの種類の例。
顧客が使う可能性のあるキーフレーズ。
このデータコネクタを起動するのが適切な一般的なシナリオ。
例としてAI推奨テンプレートもご覧ください。
具体的に説明する
このデータコネクタを使用すべき状況と提供すべき詳細の種類を明確に説明してください。
良い例 | このデータコネクタを使って顧客の注文に関する詳細を取得し、注文関連の問題解決を支援してください。このデータコネクタは注文状況、購入商品、配送先住所、追跡情報などの注文に関するすべての詳細を提供します。 |
悪い例 | このデータコネクタを使って注文に関する情報を取得してください。 |
代名詞の使用を避ける
「we」「us」「their」などの代名詞は、会社名などの適切な固有名詞に置き換えてください。
良い例 | このデータコネクタを使ってExamplyで顧客の電力使用量を調べてください。 |
悪い例 | このデータコネクタを使って彼らの電力使用量を調べてください。 |
具体的にする
このデータコネクタを起動するのが適切な一般的なシナリオを使用してください。
良い例 | このデータコネクタを使って未解決のインシデントを調べてください。例えば、インシデントの開始時刻、現在の状況、影響を受けている製品やサービス、システムのパフォーマンスが正常に戻ったかどうかなどです。 |
悪い例 | このデータコネクタを使って未解決のインシデントを調べてください。 |
顧客のフレーズを含める
過去の会話で顧客がどのように問い合わせを表現したかを確認し、彼らが使うキーワードやフレーズを含めてください。
良い例 | 「failed order」「issue with orders」「orders not appearing in the system」「difficulty with order」などのキーフレーズを探してください。 |
悪い例 | 顧客の重要なフレーズを含めていない。 |
適切なAPIエンドポイントを選ぶ
顧客に正しいデータを提供するためには、サードパーティアプリや自社所有の外部システムのいずれであっても、適切なAPIエンドポイントを選ぶことが重要です。
どこから始めればよいかわからない場合は、必要なデータを返すAPIを特定するためにエンジニアに相談するとよいでしょう。
例えば、顧客の予約詳細を保存する内部予約システムがある場合、そのシステムの予約詳細に直接アクセスできるAPIを使用したいでしょう。
また、IDやメールアドレスなどの一意の識別子をパラメータとして顧客の詳細を検索できるAPIを使用したいでしょう。
顧客の名前やメールアドレスをリクエストパラメータに使い、複数の予約がある場合は、予約日でさらに指定する必要があります。複数のデータを要求するよりも、予約IDだけを求めるのが最適です。
こうすることで、会話中にFinが顧客からこの情報を取得するよう促すためのデータ入力として予約IDを収集できます。その後、URL入力フォームのメニューをホバーしてエンドポイントにIDを挿入できます。
ヒント：データコネクタはJSONとXMLのAPIレスポンスの両方をサポートしています。外部システムがXMLのみを提供していても、Intercomが自動的にXMLをJSONに変換するため、Fin、Workflows、Inboxで追加の手順なしにデータを使用できます。
リクエストに正しいHTTPヘッダーを使用していることも確認してください。多くのデータコネクタで使用する場合は、認証トークンとして保存し、ワークスペースに安全に保存できます。
同じ予約の例で、顧客が別の日に旅行を再予約したい場合、料金と空き状況を確認するデータコネクタがあれば、Finは同じ会話内で自動的にそれを選択します。
データコネクタ用のAPIエンドポイントを選ぶ際、顧客が必要とするデータが複数のエンドポイントにまたがる場合を考慮するとよいでしょう。
顧客が料金と空き状況を確認できるように、その情報を含むエンドポイントへの別のデータコネクタを作成できます。
安全でセキュアな接続を作成する
本人確認
最も安全な呼び出しには、People Objectの‘Email’または‘User ID’を使用してシステム内のユーザーと照合することを推奨します。
Intercomは現在、Messengerから送信されるメールまたはユーザーIDの値のみを検証できます。MessengerでJSONウェブトークン（JWT）を使ってユーザーを認証することを強く推奨します。
ワンタイムパスコード（OTP）によるメール認証
OTPを使ったデータコネクタのメール認証を利用して、データコネクタ使用前に顧客がメールで送信された一意で時間制限のあるコードで本人確認を行う追加の検証ステップを提供します。
データ漏洩からの保護
データが漏洩する主な方法は一般的に2つあります：
ユーザーが自分の属性の一つを悪意を持って更新する場合 - 例えば、「user_shopify_id=123」と設定し、123は被害者のShopify IDです。その後、このデータがShopifyからID 123に対してプッシュまたはプルされ、Intercom内で悪意のあるユーザーに関連付けられます。
ユーザーが第三者のデータを操作し、データコネクタが改ざんされたデータをIntercomに取り込む場合 - 例えば、ユーザーが被害者の電話番号を使って第三者にサインアップします。その後、データコネクタが第三者に問い合わせ、その電話番号をIntercomのpeople属性に同期します。これにより、ユーザーは自分の電話番号を被害者のものに上書きします。
これを防ぐために、データコネクタを本番環境に設定する前に必ずテストして、正しく設定されていることを確認してください。
注目すべきポイント：
データコネクタが一致したユーザーに関連するデータを返していることを確認してください。
データがマッピングされたIntercom属性に正しく保存されていることを確認してください。
データ変換を使ってデータを制限する
APIからの非構造化または過大なペイロードは、Finや他のAIエージェントのようなAIベースの応答が幻覚を起こしたり、誤解したり、明確な回答を提供できなくなる原因となります。データコネクタでコードブロックを使用することで、バックエンドの変更やサードパーティ統合なしに、API応答をプログラム的に前処理、フィルタリング、調整してFinに送信したりIntercomオブジェクトにマッピングしたりできます。
ヒント：
メインの結果には必ず
returnを使うデバッグ用にのみprintを使う（例：
print('Processing order', order['id'])）。シンプルに保つ：一度にすべてを変換するのは避け、コードブロックごとに明確な変換を1つだけ行うのが最適です。
出力の形状を検証する：出力がFin（またはマッピングステップ）が期待するものであることを確認してください。
承認されたモジュール以外のインポートは禁止：標準Pythonモジュール（
math、decimal、re、datetime、datetime.timezone、json、random、time）。必要に応じて今後モジュールを追加予定です。
実用例
ここに4つの一般的なパターンと、最新の要件（returnを含む）を使った現実的な例があります。
1. Fin向けの大きなペイロードの削減
APIはしばしば過剰なデータを返します。例えば、応答に1,000件の製品が含まれていても、Finの幻覚を避けるために最初の5件だけを取得したい場合があります。
api_response = inputs['data']
# Reduce payload to just the first 5 products
result = api_response[:5]
return result
2. API応答の日付処理
LLM（Finなど）は特にタイムゾーン付きの日付文字列を誤解することがあります。Pythonを使ってすべての日付文字列を明示的なUTCの統一ISO形式に変換してください。
import datetime
def to_iso_utc(date_str):
try: # Adjust this format as needed!
dt = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
dt = dt.replace(tzinfo=datetime.timezone.utc)
return dt.isoformat()
except Exception as e:
print(f"Error parsing {date_str}: {e}")
return date_str
api_response = inputs['data']
for item in api_response:
if 'created_at' in item:
item['created_at'] = to_iso_utc(item['created_at'])
return api_response
3. 特定のフィールド値でAPI結果をフィルタリング
例えば、makeが'toyota'の車だけを返したい場合（スクリーンショットを参照してください！）
api_response = inputs['data']
filtered = [car for car in api_response if car.get('make', '').lower() == 'toyota']
return filtered
4. 最近の注文のネストされたラインアイテムをフラット化
API応答が深くネストされている場合（注文ごとにラインアイテムがあるなど）、Fin向けにフラット化してください：
orders = inputs['data']['orders']
result = []
for order in orders:
for item in order['line_items']:
result.append({
"order_id": order['id'],
"item_name": item['name']
})
return result
データコネクタからクリック可能なディープリンクを返す
データコネクタがFinにクリック可能なリンクとして表示したいURLを返す場合、2つの方法があります。
オプション1：API応答でリンクをフォーマットする
APIが返すテキストに直接マークダウンリンク構文を含めます。Finは会話内でクリック可能なリンクとして表示します。
カスタムリンクテキストを表示するにはこの形式を使います：
[View Dashboard](beyond://account/dashboard)
URL自体を表示してクリック可能にしたい場合はこの形式を使います：
[beyond://account/dashboard](beyond://account/dashboard)
オプション2：Finのガイダンスを使ってリンクをフォーマットする
APIがデータ属性にプレーンなURLを返す場合、Finにガイダンスを与えてマークダウンリンク構文でクリック可能なリンクとして表示させることができます。データコネクタ名とディープリンクを含む属性を参照してください。
オーディエンスルールを活用する
データコネクタを始めたばかりの場合、どのデータコネクタ設定がより多くの解決につながるか試したいかもしれません。その方法の一つは、まず一部のusersに対してデータコネクタを有効にしてパフォーマンスを確認することです。これはaudience rulesを使って行えます。
オーディエンスルールは、ワークスペースですでに利用可能な会社または連絡先属性のリストから選択できます。Shopify、Statuspage、Stripeをインストールしている場合は、アプリ固有の属性にもアクセスできます。
使用したい属性が存在しない場合は、カスタムデータ属性を設定して、データコネクタのターゲットにしたい条件を満たすusersを特定できます。
ルールを作成すると、データコネクタによる応答を受け取る可能性のあるusersのプレビューを確認できます。
コネクタを保護するためにセキュリティチェックを使用する
コネクタを本番環境に設定する前に、セキュリティタブで組み込みのセキュリティチェックを実行してください。これにより潜在的なリスクが表示され、実行可能な推奨事項が提供されるため、本番環境に移行する前に情報に基づいた判断ができます。
チェックには以下が含まれます：
顧客データ属性が検証されていません — 顧客データ属性がユーザー検証なしで更新可能な場合は、ユーザー検証を追加してください。
このコネクタ用にFinが収集するデータはレビューが必要です — FinがAPI呼び出し前に顧客情報を収集する場合は、まずバックエンドで入力を検証してください。
このデータコネクタを使用するWorkflowsはレビューが必要です — 特定のworkflowsが機密顧客データを露出するリスクがある場合は、バックエンドで検証してください。
このデータコネクタのリクエストヘッダーはレビューが必要です — 顧客情報が各リクエストで送信される場合は、APIがその値を検証していることを確認してください。
各チェックには問題を解決するための明確な手順が含まれています。コネクタをライブに設定する前に、すべてのフラグ付きリスクを解決してください。
会話を分析して最適化を促進する
各データコネクタには専用のヘルスダッシュボードがあり、影響を評価しパフォーマンス向上の機会を見つけることができます。設定 > Integrations > data connectors に移動し、任意のコネクタをクリックしてダッシュボードを開きます。そこから成功率、実行遅延、HTTPステータスの内訳、失敗タイプの分類を確認でき、最大14日間のプリセット時間ウィンドウまたはカスタム日付範囲でフィルタリング可能です。個別の実行詳細はLogsタブを選択してください。
ダッシュボードのほかに、data connectorが使用された会話を確認して、うまくいった点や問題点を把握しましょう。
カスタムデータ属性を使って対象を絞っている場合、その属性を利用してinboxをフィルタリングし、パフォーマンスを確認し、調整が必要かどうかを判断できます。
検討すべきいくつかの質問：
data connectorは正しいケースで発動しましたか？
チームメンバーが介入する必要がありましたか？もしあれば、どの段階でですか？
data connectorは顧客の質問に基づいて正しい情報を提供しましたか？しかし顧客の質問は実際には別のことに関するものでしたか？
回答はKnowledge Hubの追加情報で補強できましたか？
Finはカスタム属性やイベントデータをクエリして回答することはできません。Finがリアルタイムの資産データで応答できるようにするには、API経由で外部データソースにアクセスできるようにData Connectorsを設定してください。