mode="webhook" の公開可能キーで開始された場合、ThunderPhone は
レガシー webhook URL に ブロッキング
telephony.incoming / web.incoming リクエストを送信し、設定レスポンスを最大 10 秒間待機します。この
やり取りを使用して、通話ごとにプロンプト、音声、ツールを動的に選択できます。エンドツーエンドのパターンについては、
動的通話設定ガイドを参照してください。
登録済みの webhook エンドポイントも
telephony.incoming / web.incoming を受信します。対象はエージェント設定の有無にかかわらず、すべての
着信通話およびウェブセッションです。ただし、これらの配信は event_id を含む
fire-and-forget 通知であり、ブロッキングではありません。
このページの設定やり取りを処理するのは、レガシーの単一 URL webhook のみです。エンドポイント通知の形式については、
イベントカタログを参照してください。502/422 で失敗します)。
迅速に応答してください。判断中、発信者には呼び出し音が聞こえています。
リクエストペイロード
電話通話(telephony.incoming)の場合:
ウェブウィジェットセッション(
web.incoming)では、data は電話番号ではなく
埋め込みページを識別します:
webhook モードのウィジェットは、設定されている場合は公開可能キー自身の
webhook_url にこのリクエストを配信し、設定されていない場合は組織レベルの
webhook URL にフォールバックします。いずれの場合も、組織 webhook の secret で署名されます。レスポンススキーマ
この通話のエージェント設定を記述する JSON オブジェクトを返します。prompt と voice は必須で、その他はすべて任意です。
不明なトップレベルキーは暗黙的に無視されます。フィールド名を
誤記しても設定は拒否されず、単に適用されません。発話順序と
max_hold_seconds はここでは受け付けられません。これらは
エージェント自体でのみ設定できます。prompt と voice は必須であるため、{} またはバリデーションに失敗する
レスポンスを返すと、通話は 422 で拒否されます。このパスでは
静的エージェントへのフォールバックはありません(Webhook モードの
番号またはキーには、エージェントが割り当てられていません)。
ハンドラーの例
関数ツールを含むレスポンス
AI が会話中に API を呼び出せるよう、ツールを追加します。プロダクトティア早見表
関連
telephony.complete / web.complete
通話終了時のノンブロッキングイベント。
関数ツール
tools[] の完全なJSONスキーマと署名付きエンドポイント契約。Webhookエンドポイント
複数のURLを
telephony.incoming / web.incoming に登録。動的な通話設定
発信者ごとのプロンプト、ツール、A/Bテストのパターン。