Data connectorsはAPIを使用して外部システムに接続し、既存データの取得や更新を行います。そのため、IntercomでData connectorsを設定する際にはいくつかのポイントを押さえておくことが重要です。
サードパーティAPI（Shopify、WooCommerceなど）の利用
IntercomのData connectorsでサードパーティ（社内開発ではない）APIを利用する場合、その動作やリクエストに対するレスポンスをほとんど制御できないことが多いです。
とはいえ、以下のガイドは有用な指針ですが、一部のセクションはあなたのユースケースに完全には適用されない場合があります。
ファーストパーティAPIの利用
当社のエンジニアが、IntercomのFinおよびData connectorsで動作するよう既存APIを設計または修正する際の注意点をまとめました。
認証と識別に関する考慮事項
Data connectorsで使用するユーザーおよびユーザー入力のセキュリティ確保方法
重要：あなたやセキュリティチームはリスク評価を実施し、データ漏洩の影響を評価すべきです。
Intercomは、あなたや第三者APIの不適切な認証・識別の実践によるデータ漏洩について、一切の責任を負いません。
まず、Messenger SecurityをJWTで有効化することを強く推奨します。Messengerのセキュリティ確保は統合設定で最も重要なセキュリティ対策です。
また、JavaScript APIを通じて複数の属性に署名できるため、REST APIなど別の統合を使わずにMessenger経由でユーザー情報を安全に送信できます。
安全にデータを送信する利点を活用するために、属性を不正なMessenger更新から保護し、JWTを安全なソースとみなしてユーザーのフィールドを更新できます。これは、Data connectorsが機密データを扱ったり操作したりする場合に重要です。
例えば、Data connectorが「GET /accounts/<account_id>/invoices」APIリクエストを行う場合、account_idが保護されていなければユーザーがaccount_idを列挙してデータを収集できてしまいます。しかし、「GET /pizza-order-status/<order_id>」のようなリクエストでは、order_idの信頼性を気にせず、情報が正しい人に表示されるかどうかを気にしない場合もあります。
さらに、Data connectorがユーザーを一意に識別するために使用する属性（例えばメールアドレス）が信頼できることを確認すべきです。つまり、Data connectorの識別属性のソースを信頼している必要があります。例えば、Data connectorがuser_idでユーザーを識別する場合はuser_id属性に署名し、メールや他の属性で識別する場合はその属性が保護され、エンドユーザーからの検証なしに収集されないようにします。
これにより、悪意のある者が他人のメールアドレスを使って「メールで銀行取引明細を取得」などのData connectorにアクセスし、機密の金融データを露出させることを防ぎます。
可能な限り、メールをユーザーのデータ取得の主要識別子として使用しないことを推奨します。代わりに、推測不可能な一意のユーザーIDなど、よりランダムなものを使いましょう。
リードの本人確認を行うために、当社チームは現在、サポートにリードとして連絡する際の本人確認を支援するワンタイムパスワード（OTP）機能を開発中です。この機能に興味がある場合は、Messenger経由でサポートチームにお問い合わせください。導入をサポートします。
また、ユーザーが許可されていないData connectorsを実行できないようにすべきです。例えば、注文IDを知って他人の注文をキャンセルするなど。この認証・認可のロジックはIntercom内で処理されないため、あなたやセキュリティチームがリスク評価を行い、適切な方法を検討してください。
Data connectorのAPI呼び出しを安全に設定する方法
Intercomは現在、静的トークン、HTTPトークン、およびOAuth（クローズドベータ、詳細はMessengerでお問い合わせください）をサポートしています。どのトークンを使う場合でも、秘密を厳守し、漏洩した場合は速やかに更新する責任があります。ベストプラクティスとして、可能な限りOAuthトークンの使用を推奨します。
データに関する考慮事項
理想的には、APIはWorkflowに必要なデータのみを返すべきですが、現実的にはWorkflowの実行に不要な多くのデータを返すことがあります。
Data connectorsおよびFin Workflows専用にAPIを一から構築する場合、以下のいずれかの方法が考えられます。
Workflowのビジネスロジックを1つのData connectorで処理できるようAPIを構築する。これによりAPI呼び出し回数が減り、ロジックが一箇所にまとまります。
注文検索、注文詳細取得、注文の返金など個別のエンドポイントを構築する。これはRESTful APIのベストプラクティスに沿っていますが、1つのWorkflow（例：注文返金）を完了するために複数のAPI呼び出しが必要です。
APIが返すデータの内容や量を決める際に考慮すべき点には以下があります。
Fin/Workflowがワークフローのステップを完了するために本当に必要なデータだけを提供しているか？例えば、注文返金のワークフローでは注文の詳細だけが必要で、特定ユーザーのアカウント情報は不要です。
Data connectorsは接続に最大3秒、レスポンスに最大30秒待機します。APIの応答が遅い場合は、処理内容や返すデータ量を減らすことを検討してください。
完了に時間がかかるData connectorsには“Wait for webhook”機能の利用を推奨します。Data connectorsは1〜2階層のネストされた属性や配列には簡単にアクセスできますが、深くネストされた複雑なオブジェクトはFin Proceduresで処理するのが適しています。これらのレスポンスオブジェクトをData connectorで使うと困難が生じる場合がありますが、Fin Tasksはより適切に処理できます。
注意：Data connectorが実行される場所（Fin Procedures、Workflows、Inbox）に関わらず同じタイムアウトが適用されます。Procedures専用のタイムアウトはなく、顧客が設定変更できません。長時間のAPI呼び出しを伴うWorkflowやProcedure設計時に重要です。
さらに、ユーザーが不正なデータを入力したり自由入力できる機能は常に排除すべきです。
例えば、ユーザーにアカウントIDを直接入力させるのではなく、既知の安全な識別子に基づくアカウントIDを提示し、ドロップダウンリストから選択させるべきです。ユーザーからのデータ収集方法の詳細はこちらをご覧ください。
その他の考慮事項
APIは、1日あたりの返金上限などアプリケーション固有の制限を強制すべきです。
Finは同じ返金リクエストを複数回送信する可能性があるため、APIは冪等性を確保してください。
Data connectorで指定された形式にすべての入力が準拠していることをサーバー側で検証してください。
AI生成フィールドに幻覚や悪意のある内容が含まれる可能性があるため、入力データのサニタイズを実施してください。
Finが適切に対応できるよう、標準的なHTTPエラーコードを使用してください。例えば、HTTP 429や500エラーは再試行の対象となり得ますが、HTTP 410は再試行しないことを示します。
APIのバージョニングを行い、Live Fin Data connectorsのバージョン間移行（例：/v1/ordersから/v2/orders）を円滑にしてください。
まとめ
JWTでMessengerを保護し、ユーザーデータと属性を守る。
信頼できる識別子を使用（例：署名済みユーザーID、メールではなく）してデータを取得。
ユーザーの操作を制限し、許可された範囲内に留める。
自由入力を避ける — 既知で安全なソースからのドロップダウンを使用。
安全なAPIトークンを選択、理想的にはOAuth（クローズドベータ）。
必要なデータのみ返すことで遅延やデータ漏洩を防ぐ。
明確なAPI構造を使用 — シンプルなレスポンス、適切なバージョニング、標準エラーコード。
すべての入力を検証し、ユーザーやAI生成のデータをサニタイズ。