Meta Business Agent 回显消息已更新

功能说明

订阅 whatsapp.echo_message.updated。当 YCloud 处理通过 API 创建的 Meta Business Agent 匹配的出站回显状态时，您会收到此事件。请保留来自已创建事件中的消息内容：状态更新会省略消息内容和 type。失败的更新会包含源错误详情（若可用）。当前协议保持事件名称不变，并在 whatsappMessage 下公开状态变更，与对应已创建事件所使用的对象保持一致。

准备工作

通过公开 REST API 接入 Agent。
在同一账户中订阅一个活跃的 Webhook 端点到 whatsapp.echo_message.updated。
针对原始请求体验证 YCloud-Signature，持久接收每个事件，并进行幂等处理。

控制台创建的 Agent 不会发送此客户 Webhook。其 Inbox 同步是一个独立的流程。

有关端点设置，请参阅配置 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 投递。
在其回显记录之前收到的状态可在内部进行重试。请勿依赖投递顺序。
常规 API 发送的消息状态使用 whatsapp.message.updated，而不是此事件。

请求

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

响应

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

回显消息已送达

请求

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

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

响应

HTTP/1.1 200 OK

说明

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

回显消息已读

请求

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

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

响应

HTTP/1.1 200 OK

说明

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

已读后延迟到达的已发送状态

请求

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

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

响应

HTTP/1.1 200 OK

说明

将此事件保留在投递历史记录中，但切勿降级较晚的当前状态（例如 read）。

回显消息失败

请求

这是一条单独的失败消息，并非来自已读状态的转变。失败的更新会包含源错误详情（若可用）。

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

响应

HTTP/1.1 200 OK

说明

当源回调提供 errorCode 和 errorMessage 时，可将其用于诊断。

开始使用

指南

接口

Webhooks

Meta Business Agent 回显消息已更新

功能说明

准备工作

运作机制

请求

响应

回显消息已送达

请求

响应

说明

回显消息已读

请求

响应

说明

已读后延迟到达的已发送状态

请求

响应

说明

回显消息失败

请求

响应

说明

相关示例

​功能说明

​准备工作

​运作机制

​请求

​响应

​回显消息已送达

​请求

​响应

​说明

​回显消息已读

​请求

​响应

​说明

​已读后延迟到达的已发送状态

​请求

​响应

​说明

​回显消息失败

​请求

​响应

​说明

​相关示例

功能说明

准备工作

运作机制

请求

响应

回显消息已送达

请求

响应

说明

回显消息已读

请求

响应

说明

已读后延迟到达的已发送状态

请求

响应

说明

回显消息失败

请求

响应

说明

相关示例