工作原理
- 您订阅
telephony.incoming(电话)或web.incoming(小组件) 事件。两者都是阻塞式 Webhook:ThunderPhone 在继续通话前最多会 等待您的响应 10 秒。 - ThunderPhone 会向您发送
{call_id, from_number, to_number}(小组件 会话会携带小组件专用字段而非号码——请参阅 请求架构)。 - 您的服务器返回一个智能体配置(提示词、语音、产品、工具)。ThunderPhone 会在该通话中使用此配置。
- 如果您返回
{}、超时或出错,则会回退使用静态分配的 智能体。这是一种安全的默认行为。
无论是电话通话(
telephony.incoming)还是小组件
会话(web.incoming),无论是发送到 Webhook 端点还是旧版单 URL
Webhook,其工作方式都相同。1. 配置 Webhook 目标地址
- 电话通话
- Web 小组件
对于电话号码,请为您的端点订阅 响应包含一次性
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 哈希 → 分桶;对 0..49 提供提示词 A,对 50..99 提供提示词 B。在您自己的数据库中记录所选分桶,随后与已完成通话的评分进行关联。
基于时间的路由
营业时间 → “人工支持”智能体;非营业时间 → “留言”智能体。在处理程序中仅根据new Date().getUTCHours() 进行切换。
后续步骤
来电 webhook 参考
精确的请求和响应架构,包括每个配置键。
验证 webhook 签名
一次正确实现 HMAC;随处复用。
构建工具集成
将动态路由与每个智能体的工具相结合。
投递语义
重试、排序、超时。