Skip to main content
當來電撥入一個未指派智慧體的號碼,或網頁小工具工作階段透過 mode="webhook" 的可公開金鑰啟動時,ThunderPhone 會向你的 舊版 webhook URL 傳送一個阻塞式 telephony.incoming / web.incoming 請求,並最多等待 10 秒 以取得設定回應。使用此交換流程,為每通電話動態選擇提示、語音與工具—— 如需端對端模式,請參閱動態通話設定指南
已訂閱的 webhook 端點 也會收到 telephony.incoming / web.incoming——針對每一個來電與 網頁工作階段,無論是否已設定智慧體——但這些傳送皆為帶有 event_id 的即發即忘通知,絕不會阻塞。只有舊版單一 URL webhook 會承載本頁所述的 設定交換流程。端點通知格式請參閱 事件目錄
此阻塞式交換流程沒有備援:如果你的處理常式回傳非 2xx 狀態、逾時, 或回傳未通過驗證的設定,通話將遭拒絕(電話不會接通;小工具工作階段 請求會以 502/422 失敗)。請快速回應——當你進行判斷時,來電者會 聽到回鈴音。
透過 webhook 設定的通話不會附帶 ThunderPhone 同意公告。 透過此交換流程設定的通話會略過智慧體層級的通話開始公告,且明確排除於 ThunderPhone 的同意公告架構之外(服務條款的「錄音與同意」章節)。 你的組織必須獨自負責這些通話所需的所有錄音、監控、AI 參與及來電者身分 識別通知與同意事項——通話仍可由 AI 錄音、轉錄、分析及處理。在啟用此 路徑前,請先將必要揭露事項納入你自己的通話流程。

請求酬載

電話通話(telephony.incoming):
網頁小工具工作階段(web.incoming)的 data 會識別嵌入頁面,而非 電話號碼:
當已設定時,webhook 模式的小工具會將此請求傳送至可公開金鑰本身的 webhook_url,否則會改用組織層級的 webhook URL。無論哪種方式, 都會使用組織 webhook 的 secret 進行簽署。

回應結構

回傳一個描述此次通話智慧體設定的 JSON 物件。 promptvoice 為必填欄位;其他欄位皆為選填。
未知的頂層鍵會被靜默忽略——拼錯的欄位名稱不會拒絕設定, 只是無法套用。此處不接受說話順序與 max_hold_seconds; 它們只能在智慧體本身設定。
由於 promptvoice 為必填欄位,回傳 {} 或任何未通過驗證的 回應都會以 422 拒絕通話——此路徑沒有靜態智慧體備援機制(Webhook 模式中的號碼或金鑰沒有指派智慧體)。

回應大小限制

設定回應限制為 5 MiB。如果處理常式回傳更大的回應,即使狀態為 2xx,ThunderPhone 也會回報該回應超出限制,並拒絕通話或小工具工作階段。 請只在回應中保留通話設定所需的欄位;大型資料應透過函式工具或其他服務 提供,而非嵌入設定中。

處理常式範例


搭配函式工具的回應

附加工具,讓 AI 能在對話途中呼叫你的 API:
工具端點請求會使用與簽署此交換內容的相同組織 Webhook 密鑰進行簽署。請參閱 函式工具,了解確切結構與已簽署的 請求格式。

產品層級速查表


相關內容

telephony.complete / web.complete

非阻塞式的通話結束事件。

函式工具

tools[] 的完整 JSON 結構描述,以及已簽署端點合約。

Webhook 端點

將多個 URL 訂閱至 telephony.incoming / web.incoming

動態通話設定

依來電者設定提示、工具與 A/B 測試的模式。