功能说明
订阅 whatsapp.echo_message.updated。
当 YCloud 处理通过 API 创建的 Agent 的匹配出站副本状态时,你将收到此事件。请保留来自已创建事件的消息内容:状态更新会省略消息内容和 type。失败的更新会在可用时包含源错误详情。
当前契约保持事件名称不变,并在 whatsappMessage 下公开状态变更,与对应已创建事件所使用的对象保持一致。
准备工作
- 通过 公开 REST API 接入 Agent。
- 在同一账户中将一个处于活跃状态的 Webhook 端点订阅到
whatsapp.echo_message.updated。
- 根据原始请求体验证
YCloud-Signature,持久接收每个事件,并以幂等方式进行处理。
通过控制台创建的 Agent 不会发出此客户 Webhook。它们的收件箱同步属于单独的流程。
端点设置请参阅配置 Webhook。
工作原理
所有示例均使用占位标识符。请通过外层 type 进行路由并读取 whatsappMessage,而不是 whatsappMetaBusinessAgent、whatsappEchoMessage 或 data。
使用外层 id 对重复推送进行去重。外层 createTime 为 Webhook 事件时间;嵌套的 updateTime 以及特定于状态的时间均为 RFC 3339 源时间。
- 通过作用于你的账户和商业号码的
id 或 wamid,将更新与已创建事件进行匹配。
- 客户电话和 BSUID 彼此独立。当源状态同时提供
recipient_id 和 recipient_user_id 时,事件将包含 to 以及 recipientUserId 或 parentRecipientUserId。
- 如果某个状态项省略了这些身份标识,且同一回调中恰好包含一个联系人,则 YCloud 可以使用该联系人显式的
wa_id 和 user_id。如果有零个或多个联系人,则缺失的身份标识将继续保持省略;绝不会相互推断。
- 仅当源回调提供有效的商业显示电话号码时,才会包含
from。它不是从 phoneNumberId 派生出来的。
- 请将事件历史记录与当前消息状态分开管理。延迟的
sent 事件可能会在 read 之后到达;记录该事件,但不要降级当前状态。
- 下面的延迟发送示例对应于已读示例中的消息。失败示例则对应于另一条不同的消息。
- 在处理过程中,重复的同级别未变更状态会被抑制。这并不保证 HTTP 的恰好一次(exactly-once)投递。
- 在其副本记录之前收到的状态可以在内部进行重试。请勿依赖接收顺序。
- 通过普通 API 发送的消息状态使用
whatsapp.message.updated,而不是此事件。
YCloud 会在发送到你配置的 Webhook URL 的 HTTP POST 请求中包含这些 JSON 正文。
在持久接收每个事件后,返回 2xx 响应。耗时任务请以异步方式处理。
副本消息已送达
通过 id 或 wamid 与已创建事件进行关联。已更新事件会省略消息内容和类型。
记录已送达状态变更,并保留在已创建事件中收到的消息内容。
副本消息已读
通过 id 或 wamid 与已创建事件进行关联。已更新事件会省略消息内容和类型。
记录已读状态变更,使用 updateTime 和 readTime 作为源事件时间。
已读后到达的延迟发送状态
级别较低的源状态可能会在已读后到达。记录该事件,但不要降级当前的实际消息状态。
将此事件保留在投递历史记录中,但不要降级诸如 read 这样更靠后的当前状态。
副本消息失败
这是一条单独的失败消息,并非从已读状态发生转变。失败的更新会在可用时包含源错误详情。
当源回调提供时,使用 errorCode 和 errorMessage 进行诊断分析。
相关示例