運作方式
- 訂閱
telephony.incoming(電話)或web.incoming(小工具) 事件。兩者都是阻塞式 Webhook:ThunderPhone 會在繼續通話前,最多等待 10 秒以取得你的回應。 - ThunderPhone 會傳送
{call_id, from_number, to_number}給你(小工具 工作階段會傳送小工具專用欄位,而非號碼——請參閱 請求結構描述)。 - 你的伺服器會回應一個智慧體設定(提示詞、語音、 產品、工具)。ThunderPhone 會在該通話中使用此設定。
- 若你回傳
{}、逾時或發生錯誤,系統會使用靜態指派的 智慧體作為備援。安全的預設行為。
無論是電話通話(
telephony.incoming)還是小工具
工作階段(web.incoming),無論傳送至 Webhook 端點
或舊版單一 URL Webhook,運作方式皆相同。1. 設定 Webhook 目的地
- 電話通話
- 網頁小工具
針對電話號碼,將你的端點訂閱至 回應會包含一次性
telephony.incoming:secret——請儲存它;你將用它
進行簽章驗證。2. 實作處理常式
三項實用原則:- 在每個請求中驗證簽章(請參閱 驗證 Webhook 簽章)。 即使在開發環境也不要略過——一次做好,之後重複使用。
- 快速回應。十秒是硬性上限,而每一秒對來電者而言都是 無聲等待。若有需要可以查詢資料庫,但不要同步呼叫下游 LLM——若要動態產生提示詞,請預先運算並快取。
- 妥善回退。任何非預期狀態都應回傳
{},讓靜態指派的智慧體處理通話。
3. 回應結構描述
回應本文會完全符合 來電回應結構描述。 常用欄位如下:Webhook 回應不提供單次通話的發話順序和
max_hold_seconds。
請在你所參照的
智慧體上設定這些項目。模式
已登入使用者情境
在 webhook 模式的小工具中,訪客所在頁面已經知道其身分。使用小工具 SDK 會轉送的查詢字串參數(?customer_id=123)呼叫你的 webhook,並在伺服器端查詢客戶資料。
A/B 提示詞發布
在自行實作前,請注意 ThunderPhone 內建 實驗功能 (/dashboard/experiments 與智慧體建置工具中的 A/B 分頁),可定義變體、分配流量,並比較各變體的結果——無需 webhook。
若你仍需要在 webhook 端控制:將 call_id 雜湊至 bucket;對 0..49 提供提示詞 A,對 50..99 提供提示詞 B。在你自己的資料庫中記錄所選擇的 bucket,之後再與已完成通話的評分建立關聯。
依時間路由
營業時間 →「真人支援」智慧體;非營業時間 →「留言」智慧體。在處理常式中單純依new Date().getUTCHours() 切換即可。
後續步驟
來電 webhook 參考資料
完整的請求與回應結構描述,包括每個設定鍵。
驗證 webhook 簽章
一次正確設定 HMAC,處處重複使用。
建立工具整合
將動態路由與各智慧體專用工具結合。
傳遞語意
重試、排序、逾時。
