Skip to main content
着信電話がエージェントが割り当てられていない番号に到達した場合、またはウェブウィジェットセッションが mode="webhook" の公開可能キーで開始された場合、ThunderPhone は レガシー webhook URLブロッキング telephony.incoming / web.incoming リクエストを送信し、設定レスポンスを最大 10 秒間待機します。この やり取りを使用して、通話ごとにプロンプト、音声、ツールを動的に選択できます。エンドツーエンドのパターンについては、 動的通話設定ガイドを参照してください。
登録済みの webhook エンドポイントtelephony.incoming / web.incoming を受信します。対象はエージェント設定の有無にかかわらず、すべての 着信通話およびウェブセッションです。ただし、これらの配信は event_id を含む fire-and-forget 通知であり、ブロッキングではありません。 このページの設定やり取りを処理するのは、レガシーの単一 URL webhook のみです。エンドポイント通知の形式については、 イベントカタログを参照してください。
このブロッキング処理にはフォールバックがありません。ハンドラーが 2xx 以外のステータスを返した場合、タイムアウトした場合、または検証に失敗する設定を返した場合、 通話は拒否されます(電話は接続されず、ウィジェットセッションリクエストは 502/422 で失敗します)。 迅速に応答してください。判断中、発信者には呼び出し音が聞こえています。

リクエストペイロード

電話通話(telephony.incoming)の場合:
ウェブウィジェットセッション(web.incoming)では、data は電話番号ではなく 埋め込みページを識別します:
webhook モードのウィジェットは、設定されている場合は公開可能キー自身の webhook_url にこのリクエストを配信し、設定されていない場合は組織レベルの webhook URL にフォールバックします。いずれの場合も、組織 webhook の secret で署名されます。

レスポンススキーマ

この通話のエージェント設定を記述する JSON オブジェクトを返します。 promptvoice は必須で、その他はすべて任意です。
不明なトップレベルキーは暗黙的に無視されます。フィールド名を 誤記しても設定は拒否されず、単に適用されません。発話順序と max_hold_seconds はここでは受け付けられません。これらは エージェント自体でのみ設定できます。
promptvoice は必須であるため、{} またはバリデーションに失敗する レスポンスを返すと、通話は 422 で拒否されます。このパスでは 静的エージェントへのフォールバックはありません(Webhook モードの 番号またはキーには、エージェントが割り当てられていません)。

ハンドラーの例


関数ツールを含むレスポンス

AI が会話中に API を呼び出せるよう、ツールを追加します。
ツールエンドポイントへのリクエストは、この交換を署名したものと同じ組織の Webhook シークレットで署名されます。正確な形式と署名付きリクエストの 形式については、関数ツールを参照してください。

プロダクトティア早見表


関連

telephony.complete / web.complete

通話終了時のノンブロッキングイベント。

関数ツール

tools[] の完全なJSONスキーマと署名付きエンドポイント契約。

Webhookエンドポイント

複数のURLを telephony.incoming / web.incoming に登録。

動的な通話設定

発信者ごとのプロンプト、ツール、A/Bテストのパターン。