定義
Webhookとは、何かが起きたときや何かが必要になったときに、あるシステムが別のシステム上のURLに送るHTTPリクエストです。音声エージェントでは、Webhookツールが、通話中にエージェントが自社のエンドポイントを呼び出す手段になります。
Webhookの仕組み
多くのAPIは、呼び出されるのを待っています。Webhookは、これを逆にしたものです。送信側のシステムが、こちらが教えておいたアドレスにHTTPリクエストを送ります。受信側はURLを公開しておき、送信側がPOSTなどのメソッド、ヘッダー、ボディを付けてそのURLを呼び出します。受信側は、ステータスコードで応答します。
音声プラットフォームでは、Webhookは2つの形で使われます。
- イベントのコールバック。 通話の終了など、起きたことをプラットフォームがサーバーに通知します。文字起こしの保存や、記録の更新に使えます。
- Webhookツール。 エージェントが通話の途中で自社のエンドポイントを呼び出し、何かを調べたり実行したりして、その応答を使います。これはツール呼び出しの一種です。
CartesiaのManaged Agentsでは、Webhookツールを、URL、HTTPメソッド、パラメーター、ヘッダー、認証で定義します。Cartesiaが文書化している動作は、次のとおりです。
- URLはHTTPSでなければなりません。
- モデルは、ツールの説明をもとに、いつ呼び出すかを決めます。
- 各パラメーターは、モデル、固定値、または動的変数が埋めます。
- リクエストのタイムアウトは、既定で20秒です。
- タイムアウト、到達できないエンドポイント、2xx以外のステータスの場合は、エラーの結果がモデルに返され、通話は続きます。
音声エージェントにとって重要な理由
Webhookは、会話と自社のシステムをつなぐ接続なので、その挙動は耳に聞こえます。エンドポイントが遅ければ、無音が生まれます。エンドポイントが失敗すると、モデルが説明しなければならないエラーが返ります。だから応答のボディには、何がうまくいかなかったのかを、エージェントがそのまま使える言葉で書いてください。
受信側は、発信者が見ているつもりで設計してください。長いJSONをそのまま返すと、モデルが読むのに時間がかかるので、短く平易なテキストを返します。データを変更する操作は、繰り返しても安全にしておきます。再試行やモデルからの重複リクエストで、予約が2件入ってはいけないからです。リクエストは認証し、パラメーターはすべて自社のサーバー側で検証してください。モデルが渡す値は、見知らぬ人との会話から出てきたものだからです。
タイムアウトは、発信者が受け入れられる間に合わせて決めます。20秒のタイムアウトは、通話中に黙っているには長すぎます。時間のかかるツールには、実行の前に話す一言を組み合わせてください。
例
注文受付の回線向けの、説明用のWebhookツールです。
- メソッドとURL：GET
https://api.example.com/orders/{order_id} - 説明：「注文番号で注文状況を照会します。」
- 応答：「火曜に発送、金曜に到着予定。」
モデルは、発信者の発言からorder_idを埋め、応答を自分の言葉で話します。