Skip to main content
默认情况下,每个电话号码和可发布密钥都分配有一个静态智能体。当您需要针对每位来电者每位访客进行自定义配置时——例如 VIP 路由、已登录用户上下文、A/B 提示词测试——请切换到 Webhook 模式,让您的服务器决定。

工作原理

  1. 您订阅 telephony.incoming (电话)或 web.incoming(小组件) 事件。两者都是阻塞式 Webhook:ThunderPhone 在继续通话前最多会 等待您的响应 10 秒。
  2. ThunderPhone 会向您发送 {call_id, from_number, to_number}(小组件 会话会携带小组件专用字段而非号码——请参阅 请求架构)。
  3. 您的服务器返回一个智能体配置(提示词、语音、产品、工具)。ThunderPhone 会在该通话中使用此配置。
  4. 如果您返回 {}、超时或出错,则会回退使用静态分配的 智能体。这是一种安全的默认行为。
无论是电话通话(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 哈希 → 分桶;对 0..49 提供提示词 A,对 50..99 提供提示词 B。在您自己的数据库中记录所选分桶,随后与已完成通话的评分进行关联。

基于时间的路由

营业时间 → “人工支持”智能体;非营业时间 → “留言”智能体。在处理程序中仅根据 new Date().getUTCHours() 进行切换。

后续步骤

来电 webhook 参考

精确的请求和响应架构,包括每个配置键。

验证 webhook 签名

一次正确实现 HMAC;随处复用。

构建工具集成

将动态路由与每个智能体的工具相结合。

投递语义

重试、排序、超时。