Data connectorsは、サードパーティシステムのデータに接続してパーソナライズされた回答を提供する強力な方法です。顧客がチームメイトに手動で情報を調べてもらうのを待ったり、自分で情報を探すように案内される代わりに、Finは関連データに即座にアクセスし、パーソナライズされた返信を作成できます。

これらのData connectorsが正しく機能し、適切なシナリオで使用されるようにするために、考慮すべきベストプラクティスをいくつかご紹介します。

効果的なdata connectorのプロンプトを書く

最も重要なステップの一つは、data connectorのFinセクションで効果的なプロンプトを書くことです。

Fin AI Agentがこのdata connectorをトリガーすべきタイミングを説明するために、3〜5文を書いてください。できるだけ具体的にし、以下のいずれかまたは複数を必ず含めてください。

このdata connectorで回答される顧客の問い合わせの種類の例。
顧客が使う可能性のあるキーフレーズ。
このdata connectorをトリガーするのが適切な一般的なシナリオ。

例としてAI recommended templatesもご覧いただけます。

詳細に説明する

このdata connectorを使用すべきタイミングと提供すべき詳細の種類を明確に説明してください。

良い例	このdata connectorを使用して顧客の注文に関する詳細を取得し、注文関連の問題をトラブルシューティングします。このdata connectorは、注文状況、購入商品、配送先住所、追跡情報、その他関連する注文の詳細をすべて提供します。
悪い例	このdata connectorを使用して注文に関する情報を取得します。

代名詞の使用を避ける

「we」「us」「their」などの代名詞は、会社名などの適切な固有名詞に置き換えてください。

良い例	このdata connectorを使用してExamplyで顧客の電力使用量を調べます。
悪い例	このdata connectorを使用して彼らの電力使用量を調べます。

具体的にする

このdata connectorをトリガーするのが適切な一般的なシナリオを使用してください。

良い例	このdata connectorを使用して、未解決のインシデントを調べます。例えば、顧客がインシデントの開始時期、問題の現在の状況、どの製品やサービスが影響を受けているか、システムのパフォーマンスが正常に戻ったかを知りたい場合などです。
悪い例	このdata connectorを使用して未解決のインシデントを調べます。

顧客のフレーズを含める

過去の会話で顧客がどのように問い合わせを表現したかを確認し、彼らが使うキーワードやフレーズを含めてください。

良い例	「failed order」「issue with orders」「orders not appearing in the system」「difficulty with order」などのキーフレーズを探してください。
悪い例	顧客のキーフレーズを含めていない。

適切なAPIエンドポイントを選ぶ

顧客に正しいデータを提供するためには、サードパーティアプリや自社所有の外部システムのいずれであっても、適切なAPIエンドポイントを選ぶことが重要です。

どこから始めればよいかわからない場合は、必要なデータを返すAPIを特定するためにエンジニアに相談することをお勧めします。

例えば、顧客の予約詳細を保存する内部予約システムがある場合、そのシステムの予約詳細に直接アクセスできるAPIを使用したいでしょう。

また、IDやメールアドレスなどの一意の識別子をパラメータとして使用して顧客の詳細を検索できるAPIを使用したいでしょう。

顧客の名前やメールアドレスをリクエストパラメータとして使用し、複数の予約がある場合は、予約日の指定などでリクエストをさらに絞り込む必要があります。複数のデータを要求するよりも、予約IDだけを求めるのが最適です。

こうすることで、予約IDをデータ入力として収集でき、Finが会話中に顧客からこの情報を取得するよう促します。その後、URL入力フォームボックスの末尾のメニューにカーソルを合わせてIDをエンドポイントに挿入できます。

ヒント：Data connectorsは現在、JSONとXMLの両方のAPIレスポンスをサポートしています。外部システムがXMLのみを提供している場合でも、直接接続可能です。IntercomがXMLを自動的にJSONに変換するため、Fin、Workflows、Inboxで追加の手順なしにデータを使用できます。

リクエストに正しいHTTPヘッダーを使用していることも確認してください。これらが多くのdata connectorsで使用される場合は、認証トークンとして保存し、ワークスペースに安全に保存できます。

同じ予約の例を使うと、顧客が別の日に旅行を再予約したい場合、料金と空き状況を確認するdata connectorがあれば、Finは同じ会話内で自動的にそれを選択します。

data connectorsで使用するAPIエンドポイントを選ぶ際、顧客が必要とするデータが複数のエンドポイントにまたがる場合を考慮することもあります。

顧客が料金と空き状況を確認できるように、その情報を含むエンドポイントへの別のdata connectorを作成できます。

安全でセキュアな接続を作成する

本人確認

最も安全な呼び出しには、People Objectの‘Email’または‘User ID’を使用して、システム内のユーザーと照合することを推奨します。

Intercomは現在、Messengerから送信されるメールまたはuser IDの値のみを検証できます。MessengerでJSONウェブトークン（JWTs）を使ってusersを認証することを強く推奨します。

ワンタイムパスコード（OTP）によるメール検証

OTPを使ったデータコネクターのメール検証により、顧客がメールで送信された一意で時間制限のあるコードを使って本人確認を行う追加の検証ステップを提供できます。

データ漏洩からの保護

データが漏洩する主な方法は一般的に2つあります：

ユーザーが自分の属性の1つを悪意を持って更新する場合 - 例えば、「user_shopify_id=123」と設定し、123は被害者のShopify IDです。その後、このデータがShopifyからID 123に対してプッシュまたはプルされ、Intercomで悪意のあるユーザーに関連付けられます。
ユーザーが第三者のデータを操作し、データコネクターが改ざんされたデータをIntercomに取り込む場合 - 例えば、ユーザーが被害者の電話番号を使って第三者にサインアップします。その後、データコネクターが第三者に問い合わせ、その電話番号をIntercomのpeople属性に同期します。これにより、ユーザーは自分の電話番号を被害者のものに上書きします。

これを防ぐために、データコネクターを本番環境に設定する前に必ずテストして、正しく構成されていることを確認してください。

注目すべき重要なポイント：

データコネクターが一致したuserに関連するデータを返していることを確認してください。
データがマッピングされた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）。必要に応じて今後モジュールを追加予定です。

実用的な例

ここでは、最新の要件（returnを含む）を使った現実的な例を4つ紹介します。

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にガイダンスを与えてマークダウンリンク構文でクリック可能なリンクとして表示させることができます。データコネクター名とディープリンクを含む属性を参照してください。

注意：ディープリンクは一部のモバイルメッセージタイプでサポートされています。詳細はiOSおよびAndroidのディープリンクドキュメントを参照してください。

オーディエンスルールを活用する

データコネクターを始めたばかりの場合、どのデータコネクター設定がより多くの解決につながるか試してみたいかもしれません。その方法の一つは、まず一部のusersに対してデータコネクターを有効化し、パフォーマンスを確認することです。audience rulesを使ってこれが可能です。

オーディエンスルールは、すでにワークスペースで利用可能な会社または連絡先属性のリストから選択できます。Shopify、Statuspage、Stripeをインストールしている場合は、アプリ固有の属性にもアクセスできます。

使用したい属性が存在しない場合は、custom data attributesを設定して、データコネクターのターゲットとなる条件を満たすusersを特定できます。

ルールを作成すると、データコネクターによる応答を受け取る可能性のあるusersのプレビューを確認できます。

コネクターを保護するためにセキュリティチェックを使う

コネクターを本番環境に設定する前に、セキュリティタブで組み込みのセキュリティチェックを実行してください。これにより潜在的なリスクが表示され、実行可能な推奨事項が提供されるため、公開前に情報に基づいた判断ができます。

チェックには以下が含まれます：

顧客データ属性が検証されていない — 顧客データ属性がuserの検証なしに更新可能な場合は、userの検証を追加してください。
このコネクターのためにFinが収集するデータはレビューが必要 — FinがAPIを呼び出す前に顧客から情報を収集する場合は、まずバックエンドで入力を検証してください。
このデータコネクターを使うWorkflowsはレビューが必要 — 特定のworkflowsが機密顧客データを露出するリスクがある場合は、バックエンドで検証してください。
このデータコネクターのリクエストヘッダーはレビューが必要 — 顧客情報が各リクエストで送信される場合は、APIがその値を検証していることを確認してください。

各チェックには問題を解決するための明確な手順が含まれています。コネクタをライブに設定する前に、すべてのリスクを解消してください。

会話を分析して最適化を促進します。

各データコネクタには専用のヘルスダッシュボードがあり、影響を評価しパフォーマンス向上の機会を見つけることができます。設定 > Integrations > data connectors に移動し、任意のコネクタをクリックしてダッシュボードを開きます。そこから成功率、実行遅延、HTTPステータスの内訳、失敗タイプの分類を確認できます。すべて時間枠（1時間、6時間、24時間、7日、14日）でフィルタ可能です。個別の実行詳細はLogsタブを選択してください。ダッシュボードのほかに、data connector が使用された会話を確認して、うまくいった点や問題点を把握しましょう。

カスタムデータ属性を使って対象ユーザーを絞り込んでいる場合、その属性を使ってinboxをフィルタリングし、パフォーマンスを確認し、調整が必要かどうかを判断できます。

検討すべきいくつかの質問：