Skip to main content

功能介绍

订阅 whatsapp.echo_message.updated。 当 YCloud 为通过 API 创建的 Meta Business Agent 处理相匹配的出站 echo 状态时,您会收到此事件。请保留来自已创建事件的消息内容:状态更新会省略消息内容和 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)送达。
  • 早于其 echo 记录接收到的状态可以在内部重试。请勿依赖送达顺序。
  • 普通 API 发送的消息状态使用的是 whatsapp.message.updated,而不是此事件。

请求

YCloud 会在发送到您配置的 Webhook URL 的 HTTP POST 请求中包含这些 JSON 主体。

响应

在持久接收每个事件后返回 2xx 响应。耗时较长的操作请异步处理。

Echo 消息已送达

请求

通过 id 或 wamid 与已创建事件进行关联。已更新事件会省略消息内容和类型。

响应

说明

记录已送达(delivered)的状态转变,并保留在已创建事件中接收到的消息内容。

Echo 消息已读

请求

通过 id 或 wamid 与已创建事件进行关联。已更新事件会省略消息内容和类型。

响应

说明

使用 updateTime 和 readTime 作为源事件时间来记录已读(read)的状态转变。

已读之后的延迟已发送状态

请求

级别较低的源状态可能会在已读之后到达。记录该事件时,切勿降级您当前的消息状态。

响应

说明

将此事件保留在送达历史中,但切勿降级更新的当前状态(例如 read)。

失败的 echo 消息

请求

这是一条单独的失败消息,并非由已读转变而来。失败的更新会在可用时包含源错误详情。

响应

说明

当源回调提供 errorCode 和 errorMessage 时,可使用它们进行诊断。

相关示例