仕組み
telephony.incoming(電話)またはweb.incoming(ウィジェット) イベントを購読します。どちらもブロッキングWebhook です。ThunderPhone は 通話を続行する前に、応答を最大 10 秒間待機します。- ThunderPhone から
{call_id, from_number, to_number}が送信されます(ウィジェット セッションでは番号の代わりにウィジェット固有のフィールドが含まれます。詳細は リクエストスキーマを参照してください)。 - サーバーはエージェント設定(プロンプト、音声、プロダクト、ツール)を返します。 ThunderPhone はその設定を通話に使用します。
{}を返した場合、タイムアウトした場合、またはエラーが発生した場合は、固定で割り当てられた エージェントがフォールバックとして使用されます。安全なデフォルトです。
Webhook エンドポイントに配信する場合も、レガシーの単一 URL Webhook に配信する場合も、
電話(
telephony.incoming)とウィジェットセッション(web.incoming)で同じように動作します。1. Webhook の送信先を設定する
- 電話
- Web ウィジェット
電話番号では、エンドポイントを レスポンスには一度だけ使用できる
telephony.incoming に購読させます。secret が含まれます。保存しておいてください。署名検証に使用します。2. ハンドラーを実装する
3つの基本ルール:- すべてのリクエストで署名を検証します(Webhook署名を検証するを参照)。 開発環境でも省略せず、一度正しく実装して再利用してください。
- 迅速に応答します。上限は10秒であり、1秒ごとに発信者には無音が続きます。必要に応じてデータベース検索は行えますが、ダウンストリームのLLMを同期的に呼び出さないでください。動的なプロンプト生成が必要な場合は、事前に計算してキャッシュします。
- 適切にフォールバックします。想定外の状態では
{}を返し、静的に割り当てられたエージェントが通話を処理できるようにします。
3. レスポンススキーマ
レスポンス本文は着信通話レスポンススキーマと完全に一致します。よく使用されるフィールド:通話ごとの発話順序と
max_hold_seconds はWebhookレスポンスでは利用できません。参照するエージェントで設定してください。パターン
ログイン済みユーザーのコンテキスト
webhook モードのウィジェットでは、訪問者が誰であるかをページがすでに把握しています。 ウィジェット SDK が転送するクエリ文字列パラメータ(?customer_id=123)を付けて webhook を呼び出し、サーバー側で顧客を検索します。
A/B プロンプトのロールアウト
これを独自実装する前に、ThunderPhone にはバリアントの定義、トラフィックの分割、バリアントごとの結果比較を行うネイティブの 実験機能 (/dashboard/experiments とエージェントビルダーの A/B タブ)があることに留意してください。
webhook は不要です。
それでも webhook 側で制御する必要がある場合: call_id をハッシュ化してバケットに割り当てます。
0..49 にはプロンプト A、50..99 にはプロンプト B を提供します。選択したバケットを独自の DB に記録し、後で完了した通話の評価と関連付けます。
時間ベースのルーティング
営業時間内 → 「ライブサポート」エージェント、営業時間外 → 「メッセージ受付」エージェント。ハンドラー内でnew Date().getUTCHours() を使用するだけの単純な切り替えです。
次のステップ
着信通話 webhook リファレンス
すべての設定キーを含む、正確なリクエストおよびレスポンスのスキーマ。
webhook 署名を検証
HMAC を一度正しく設定し、どこでも再利用します。
ツール統合を構築
動的ルーティングとエージェントごとのツールを組み合わせます。
配信セマンティクス
再試行、順序、タイムアウト。