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. 用一次新的外呼验证投递
- 从同一个已授权的 WhatsApp 消息账号选取测试会话。用
POST /v1/calls准备通话,将返回的call_id与应用任务关联保存。 201响应中的state: preparing表示链接已准备好。操作员在expires_at前打开私密的join_url并点击 Start call。- 测试通话接通并结束后,查找接通事件和结束事件。将事件的
account_id、data.call.id与保存的记录核对。 - 用原有流程发送一条测试消息,确认预期消息事件仍能到达接收端。
已启用签名的端点按投递与验签指南校验原始请求体。按事件 id 去重,处理乱序到达。迟到的接通事件可以补充接通证据,通话记录保持已结束。message.* 中的通话记录有独立用途。
5. 排查缺失回调,并保留回滚所需配置
回调缺失时,先核对精确事件名、端点作用范围和启用状态,再检查接收端日志、HTTP 响应和应用存储。2xx 表示确认投递,需另外验证持久化和任务关联。投递、重试和死信重放均使用当时的资格和订阅设置。
保留原端点配置及其签名密钥引用。需要回滚时,提交原有完整配置并再次验证消息投递。需要协助时,可将端点 ID、账号 ID、通话 ID、UTC 时间和脱敏后的接收结果提供给技术支持。API key、签名密钥和完整通话链接应保持私密。
让消息接入变成一条稳定的产品管线。
先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。