Skip to main content

功能说明

订阅 whatsapp.echo_message.updated。 当 YCloud 处理通过 API 创建的 Agent 的匹配出站副本状态时,你将收到此事件。请保留来自已创建事件的消息内容:状态更新会省略消息内容和 type。失败的更新会在可用时包含源错误详情。 当前契约保持事件名称不变,并在 whatsappMessage 下公开状态变更,与对应已创建事件所使用的对象保持一致。

准备工作

  1. 通过 公开 REST API 接入 Agent。
  2. 在同一账户中将一个处于活跃状态的 Webhook 端点订阅到 whatsapp.echo_message.updated。
  3. 根据原始请求体验证 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 进行诊断分析。

相关示例