> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp 副本消息已更新

> 处理已送达、已读、延迟送达以及失败的副本消息状态事件。

## 功能说明

订阅 `whatsapp.echo_message.updated`。

当 YCloud 处理通过 API 创建的 Agent 的匹配出站副本状态时，你将收到此事件。请保留来自已创建事件的消息内容：状态更新会省略消息内容和 `type`。失败的更新会在可用时包含源错误详情。

当前契约保持事件名称不变，并在 `whatsappMessage` 下公开状态变更，与对应已创建事件所使用的对象保持一致。

## 准备工作

1. 通过 [公开 REST API](/zh/api-reference/meta-business-agents/onboard) 接入 Agent。
2. 在同一账户中将一个处于活跃状态的 Webhook 端点订阅到 `whatsapp.echo_message.updated`。
3. 根据原始请求体验证 `YCloud-Signature`，持久接收每个事件，并以幂等方式进行处理。

<Warning>
  通过控制台创建的 Agent 不会发出此客户 Webhook。它们的收件箱同步属于单独的流程。
</Warning>

端点设置请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events)。

## 工作原理

所有示例均使用占位标识符。请通过外层 `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`](/zh/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples)，而不是此事件。

## 请求

YCloud 会在发送到你配置的 Webhook URL 的 HTTP `POST` 请求中包含这些 JSON 正文。

## 响应

在持久接收每个事件后，返回 `2xx` 响应。耗时任务请以异步方式处理。

## 副本消息已送达

### 请求

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 副本消息已读

### 请求

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

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

### 请求

级别较低的源状态可能会在已读后到达。记录该事件，但不要降级当前的实际消息状态。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

将此事件保留在投递历史记录中，但不要降级诸如 `read` 这样更靠后的当前状态。

## 副本消息失败

### 请求

这是一条单独的失败消息，并非从已读状态发生转变。失败的更新会在可用时包含源错误详情。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

当源回调提供时，使用 `errorCode` 和 `errorMessage` 进行诊断分析。

### 相关示例

* [WhatsApp 副本消息已创建](/zh/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [WhatsApp Agent 移交已更新](/zh/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated)
* [副本与 Agent 移交示例](/zh/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [完整载荷目录](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.