Skip to main content
当呼入电话到达一个未分配智能体的号码,或 Web 小组件会话通过处于 mode="webhook" 的可发布密钥启动时,ThunderPhone 会向您的 旧版 webhook URL 发送一个阻塞式 telephony.incoming / web.incoming 请求,并最多等待 10 秒以获取配置响应。使用此交互可为每通电话动态选择提示词、语音和工具——有关端到端模式,请参阅动态通话配置指南
已订阅的 webhook 端点也会接收 telephony.incoming / web.incoming——针对每一通呼入电话 和 Web 会话,无论是否已配置智能体——但这些投递是包含 event_id 的即发即弃通知,绝不会阻塞。 只有旧版单 URL webhook 承载本页面中的配置交互。端点通知的数据结构请参阅 事件目录
此阻塞式交互没有回退机制:如果您的处理程序返回非 2xx 状态、超时,或返回未通过验证的配置, 则该通话将被拒绝(电话不会接通;小组件会话请求将以 502/422 失败)。请快速响应——在您作出决定期间,来电者会听到回铃音。

请求载荷

对于电话呼叫(telephony.incoming):
对于 Web 小组件会话(web.incoming),data 标识嵌入页面而非电话号码:
Webhook 模式的小组件会在设置了可发布密钥自身的 webhook_url 时将此请求发送至该 URL,否则回退至组织级 webhook URL。无论哪种方式,都会使用组织 webhook 的 secret 进行签名。

响应架构

返回一个 JSON 对象,用于描述本次通话的智能体配置。 必须提供 promptvoice;其他字段均为可选。
未知的顶级键会被静默忽略——拼写错误的字段 名称不会导致配置被拒绝,只是不会生效。此处不接受发言顺序 和 max_hold_seconds;它们只能在智能体本身上 配置。
由于 promptvoice 为必填项,返回 {} 或任何 未通过验证的响应都会以 422 拒绝通话——此路径不提供 静态智能体回退机制(Webhook 模式下的号码或密钥没有分配的智能体)。

示例处理程序


使用函数工具响应

附加工具,使 AI 能够在对话过程中调用您的 API:
工具端点请求使用与签署此次交换的同一组织 Webhook 密钥进行签名。有关确切结构和已签名请求格式,请参阅 函数工具

产品层级速查表


相关内容

telephony.complete / web.complete

非阻塞式通话结束事件。

函数工具

tools[] 的完整 JSON 架构和签名端点约定。

Webhook 端点

telephony.incoming / web.incoming 订阅多个 URL。

动态通话配置

按来电者配置提示词、工具和 A/B 测试的模式。