Skip to main content
デフォルトでは、すべての電話番号と公開可能キーに固定エージェントが 割り当てられています。発信者ごとまたは訪問者ごとのカスタマイズ (VIP ルーティング、ログイン済みユーザーのコンテキスト、A/B プロンプトテスト)が必要な場合は、 Webhook モードに切り替え、サーバー側で決定します。

仕組み

  1. telephony.incoming (電話)または web.incoming(ウィジェット) イベントを購読します。どちらもブロッキングWebhook です。ThunderPhone は 通話を続行する前に、応答を最大 10 秒間待機します。
  2. ThunderPhone から {call_id, from_number, to_number} が送信されます(ウィジェット セッションでは番号の代わりにウィジェット固有のフィールドが含まれます。詳細は リクエストスキーマを参照してください)。
  3. サーバーはエージェント設定(プロンプト、音声、プロダクト、ツール)を返します。 ThunderPhone はその設定を通話に使用します。
  4. {} を返した場合、タイムアウトした場合、またはエラーが発生した場合は、固定で割り当てられた エージェントがフォールバックとして使用されます。安全なデフォルトです。
Webhook エンドポイントに配信する場合も、レガシーの単一 URL Webhook に配信する場合も、 電話(telephony.incoming)とウィジェットセッション(web.incoming)で同じように動作します。

1. Webhook の送信先を設定する

電話番号では、エンドポイントを 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 を一度正しく設定し、どこでも再利用します。

ツール統合を構築

動的ルーティングとエージェントごとのツールを組み合わせます。

配信セマンティクス

再試行、順序、タイムアウト。