Respond by APIチャネルを使うと、Fin ProceduresのHuman-in-the-Loop（HITL）ステップをwebhookとIntercom APIを使って独自システムに接続できます。FinがHITLステップに到達すると、Intercomはwebhookをエンドポイントに送信します。システムはリクエストを処理し、必要な属性を入力して応答を返し、手続きを自動的に続行させます。
注意: この機能は現在管理された利用可能性の段階にあります。使用するには、Developer HubアプリをPreview APIバージョンに設定する必要があります。
例
この機能の利用例は以下の通りです：
自動承認ワークフロー：返金や割引の承認をビジネスルールを適用し自動応答する内部ツールにルーティング
カスタムチームメイトダッシュボード：HITLリクエストを独自のサポートツールや内部ポータルで他のタスクと並べて表示
外部チームへのエスカレーション：Intercomを使わないチーム（エンジニアリング、法務、財務など）に質問を転送し、その応答を取得
監査およびコンプライアンスログ：応答前にすべてのHITL決定をコンプライアンスシステムに記録し、自動的な記録を作成
開始前に
Respond by APIを設定するには、以下が必要です：
少なくとも1つのHuman-in-the-Loopステップを含むFin Procedure
Developer Hubアプリ — まだない場合は設定>Developer Hubで作成してください
webhookリクエストを受信できるHTTPSエンドポイント
Developer Hubアプリにはread_conversationsとwrite_conversationsのOAuthスコープが必要です
ステップ1：手続きでAsk via webhookを有効にする
設定したいprocedureをProceduresエディターで開きます。
Human-in-the-Loopステップを選択します。
歯車アイコンをクリックしてステップの設定パネルを開きます。
More channelsタブを選択します。
Ask via webhookセクションを展開します。
Enable for this procedureをオンに切り替えます。
Verify webhook setupをクリックしてDeveloper Hubアプリが正しく登録されているか確認します。
手続きを保存します。
Verify webhook setupをクリックすると、以下のいずれかが表示されます：
「Webhook connected.」— webhookが正しく設定されています
「No webhook found.」— Developer Hubでwebhookを設定する必要があります（ステップ2参照）
検証に失敗した場合は、Developer Hubをクリックしてアプリ設定を新しいタブで開きます。
注意: Ask via webhookチャネルはInboxおよびSlackチャネルと連携して動作します。HITLステップに到達すると、すべての有効チャネルに同時に通知されます。最初に応答したチャネルが勝ち、以降の応答は拒否されます。
ステップ2：Developer Hubでwebhookを設定する
設定 > Developer Hubに移動するか、直接アプリ設定にアクセスします。
アプリを選択するか、新規作成します。
API Versionに移動し、Previewに切り替えます。
アプリ設定のWebhooksに移動します。
webhookエンドポイントURLを入力します（HTTPSである必要があります）。
購読トピックにprocedure.hitl_notification.createdを追加します。
アプリに必要なOAuthスコープがあることを確認してください：read_conversations（webhook通知受信に必須）とwrite_conversations（API経由のコールバック応答送信に必須）。
webhook設定を保存します。
重要: この機能が管理された利用可能性の段階にある間、HITL webhookトピックはPreview APIバージョンでのみ利用可能です。トピックがwebhookトピックリストに表示される前に、このバージョンに切り替える必要があります。
ステップ3：webhookペイロードを処理する
手続きがAsk via webhookを有効にしたHuman-in-the-Loopステップに到達すると、IntercomはwebhookエンドポイントにPOSTリクエストを送信します。ペイロードには以下が含まれます：
会話ID
Finが尋ねている質問
システムが入力する必要のある属性
応答を送信するためのコールバックURL
コンテキスト用の最近の会話メッセージ
完全なペイロードとフィールド仕様については、procedures API referenceを参照してください。
ステップ4：コールバック応答を送信する
システムがHITLリクエストを処理したら、webhookペイロードにあるcallback_urlにPOSTリクエストを送信します。step_idとattributes_to_collectにリストされた各属性の値を含めます。write_conversations OAuthスコープを持つBearerトークンで認証してください。
応答が成功すると、Finは提供された属性値を使って手続きを再開します。OAuthトークンに関連付けられたチームメイトが応答者として記録されます。
完全なコールバックリクエスト形式、認証詳細、サポートされるデータ型、エラーコードについては、procedures API referenceを参照してください。
ベストプラクティス
統合を構築する際に以下を心がけてください：
webhook署名を検証する：IntercomはHMACでwebhookペイロードに署名します。リクエストが正当であることを確認するために必ず署名を検証してください。詳細はprocedures API referenceを参照。
タイムアウト前に応答する：HITLリクエストにはProceduresエディターで設定可能な待機時間があります。expires_atまでに応答がない場合、手続きは設定されたタイムアウト動作（エスカレーションメッセージ、再割り当てなど）を実行します。
重複応答を送信しない：コールバックは冪等ではありません。同じステップに複数回応答を送ると、後続のリクエストは409 Conflictを返します。409を受け取った場合、元の応答はすでに処理されています。
リスト属性の場合はoption idを送信：表示ラベルではなく、options配列のidを送信してください。
応答者を追跡する：OAuthトークンに関連付けられたチームメイトが応答者として記録されます。一定のIDを持たせたい場合は専用サービスアカウントの使用を検討してください。
マルチチャネル競合を適切に処理する：APIチャネルがInboxやSlackと共に有効な場合、最初の応答が勝ちます。別チャネルで先に応答があった場合、システムは409を受け取ることがあります。