← 所有文章
指南

WhatsApp 外呼开放后,普通工作区怎么接收通话回调?

UnifyPort 普通工作区已可准备 WhatsApp 单聊外呼。如果 Webhook 端点只订阅了 ["*"],消息仍然可以正常到达,外呼回调却可能缺失。要接收接通和结束事件,需分别显式订阅 call.answered 和 call.ended。

创建通话文档适用于通过 UnifyPort 非官方接口由人工发起的语音和视频外呼。call.incoming 仍为将来的呼入能力预留。

1. 核对工作区的订阅规则

工作区订阅方式外呼事件
普通["*"]、[] 或省略列表仅匹配常规事件
普通在 subscribed_events 中显式列出事件名接收列出的外呼事件
内测显式列表、通配、空列表或省略接收匹配的外呼事件

端点符合条件时,显式事件名匹配对应回调。普通工作区可以同时填写 * 和两个外呼事件名,保留常规事件的通配覆盖。普通工作区显式订阅预留的 call.incoming 会返回 403 beta_feature_not_enabled(41002)。

2. 更新前先读取端点配置

通过查询 Webhook 端点确认目标 URL、状态、当前订阅和重试策略。核对端点属于工作区还是某个消息账号。更新会保留已有的账号绑定。

更新 Webhook 端点会替换配置。提交前准备完整的目标配置,保留当前 URL、状态和重试策略。已启用签名时,从自己的安全配置中取出现有密钥。查询响应提供 signing_enabled,密钥由应用侧保管。省略 signing_secret 或传空值会关闭签名。省略重试策略会恢复为首次投递后默认重试三次。

3. 添加外呼事件,同时保留消息订阅

如果端点当前使用通配订阅,将下面的请求体提交到 PATCH /v1/webhook-endpoints/{endpoint_id}。示例假设端点已启用、启用了签名且原本配置为重试三次。用实际的 URL、状态、密钥和重试配置替换示例值。API key 和签名密钥应保存在服务端。

{
  "url": "https://support.example.com/webhook",
  "status": "active",
  "subscribed_events": ["*", "call.answered", "call.ended"],
  "signing_secret": "<EXISTING_WEBHOOK_SIGNING_SECRET>",
  "retry_policy": { "max_attempts": 3 }
}

如果端点使用显式列表,复制现有事件名,再加入两个外呼事件。例如,原列表只包含 message.received 和 message.read 时,合并后的数组如下。将该数组作为完整更新请求的 subscribed_events 字段值。

["message.received", "message.read", "call.answered", "call.ended"]

更新后再查询一次端点,核对 URL、状态、订阅、签名状态和重试设置。确认接收端可以处理两种通话事件和原有的消息事件。

4. 用一次新的外呼验证投递

  1. 从同一个已授权的 WhatsApp 消息账号选取测试会话。用 POST /v1/calls 准备通话,将返回的 call_id 与应用任务关联保存。
  2. 201 响应中的 state: preparing 表示链接已准备好。操作员在 expires_at 前打开私密的 join_url 并点击 Start call。
  3. 测试通话接通并结束后,查找接通事件和结束事件。将事件的 account_id、data.call.id 与保存的记录核对。
  4. 用原有流程发送一条测试消息,确认预期消息事件仍能到达接收端。

已启用签名的端点按投递与验签指南校验原始请求体。按事件 id 去重,处理乱序到达。迟到的接通事件可以补充接通证据,通话记录保持已结束。message.* 中的通话记录有独立用途。

5. 排查缺失回调,并保留回滚所需配置

回调缺失时,先核对精确事件名、端点作用范围和启用状态,再检查接收端日志、HTTP 响应和应用存储。2xx 表示确认投递,需另外验证持久化和任务关联。投递、重试和死信重放均使用当时的资格和订阅设置。

保留原端点配置及其签名密钥引用。需要回滚时,提交原有完整配置并再次验证消息投递。需要协助时,可将端点 ID、账号 ID、通话 ID、UTC 时间和脱敏后的接收结果提供给技术支持。API key、签名密钥和完整通话链接应保持私密。

UnifyPort API

让消息接入变成一条稳定的产品管线。

先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。