> ## 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.

# 消息状态 Webhook 示例

> 处理 WhatsApp、Messenger、Email、SMS 和 Voice 消息的状态更新。

> [!NOTE]
>
> 如需查看基于 Schema 生成的完整目录，请参阅[所有示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。

## 功能说明

处理 WhatsApp、Messenger、Email、SMS 和 Voice 消息的状态更新。

## 开始之前

* 在您的应用程序中创建一个公开的 HTTPS 端点。
* 为您需要的事件类型配置 YCloud Webhook 端点。
* 安全存储端点签名密钥。
* 确保事件处理具备幂等性。

## 工作原理

当事件发生时，YCloud 会发送一个 HTTP `POST` 请求。验证签名，持久化记录该事件，返回 `2xx` 响应，并异步处理耗时任务。

## 请求

以下场景展示了发送至您的 Webhook URL 的请求。将事件 `id` 视为传递标识符，并使用 `type` 路由有效负载。

## 响应

接收事件后返回 `2xx` 状态。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

> [!NOTE]
>
> 有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

对于 WhatsApp，在成功请求 API 发送消息后，消息的状态为 `accepted`。消息状态更新将触发 `whatsapp.message.updated` Webhook。

通常，消息状态的变化规律如下：

* 如果我们无法送达该消息，状态将变为 `failed`。
* 如果可以送达该消息，状态将变为 `sent`，随后可能会变为 `failed`、`delivered` 或 `read`。
* 如果该消息已成功送达收件人的设备，状态将变为 `delivered` 或 `read`。

但实际情况往往更加复杂。首先，我们不保证 Webhook 通知到达的顺序，尤其是在事件几乎同时发生时。其次，`delivered` 事件可能会发生在 `failed` 之后，反之亦然，特别是在最终用户使用多个设备的情况下。

## 最高出价（Max Price）消息已送达

使用已送达消息的更新来对账最高出价（Max Price）营销消息的最终费用。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_max_price_delivery",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-11-03T08:00:00.000Z",
  "whatsappMessage": {
    "id": "message_example_max_price",
    "wabaId": "<WABA_ID>",
    "from": "+15550001111",
    "to": "+15550002222",
    "type": "template",
    "status": "delivered",
    "pricingCategory": "marketing_lite_bidding",
    "bidPricingFlag": true,
    "totalPrice": 0.045,
    "currency": "USD"
  }
}
```

### 响应

持久化接收事件后返回 `2xx` 响应。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

`bidPricingFlag: true` 和 `pricingCategory: marketing_lite_bidding` 标识出价模式。在处于 `delivered` 或 `read` 时，使用 `totalPrice` 和 `currency` 作为最终费用。配置的 `maxBid` 为价格上限；在 `accepted` 或 `sent` 报告的金额为预估值。有关配置和倍数示例，请参阅 [Max Price 集成指南](https://docs.ycloud.com/zh/api-reference/guides/whatsapp-platform/max-price-integration-guide.md)。

## 消息已发送

在此情况下，您的 Webhook 端点收到了消息 `sent` 事件：

* 消息 `status` 为 `sent`，表示消息正在 WhatsApp 系统内部传输。
* 包含会话信息，包括会话过期时间以及发起来源类型。
* 包含我们可能向您收取的 **预估** `pricingCategory` 和 `totalPrice`。
* 包含 `wamid`，即 WhatsApp 平台上的原始消息 ID，以 `wamid.` 开头。

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M."
    },
    "status": "sent",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'
```

### 响应

持久化接收事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

* **`totalPrice` 仅为首条消息送达前的预估价格，当 `status` 变为 `delivered` 或 `read` 时，该价格会成为最终价格。已发送但尚未送达的消息所占用的余额，在消息被丢弃前将不可用（已发送但超过 30 天未送达的消息会被丢弃）。**

* 通常，处于 `sent` 状态的消息很快会变为 `delivered` 或 `read`，但以下情况除外：
  * 收件人的 WhatsApp 账户处于离线状态，您发送的 WhatsApp 消息将在收件人拥有可用或活跃的网络连接后才会送达。
  * 发送给已将您拉黑的联系人的任何消息将始终显示为 `sent`，且绝不会变为 `delivered`。
  * 收件人已关闭已读回执，您将不会收到消息 `read` 回执。
  * 消息随后变为 `failed` 并带有错误码 `131026`，这表示“消息无法送达”或“接收方无法接收此消息”。这极有可能是因为收件人未注册，或者正在使用过旧的 WhatsApp 版本。
  * 为保障高质量的用户体验，该消息未被送达。请参阅[每个用户的营销模板消息限制](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits)。

## 消息已送达

在此情况下，您的 Webhook 端点收到了消息 `delivered` 事件：

* 消息 `status` 为 `delivered`，表示消息已成功送达收件人的设备。

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'
```

### 响应

持久化接收事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

* 此事件表示您的企业发送的消息已送达至用户的设备。
* **状态要变为 `read`，必须先经历 `delivered`。在某些场景中，例如用户正处于聊天界面且有新消息到达时，消息几乎同时变为 `delivered` 和 `read`。在这种情况或类似场景下，系统不会返回 `delivered` 通知，因为消息已被读取即意味着已被送达。这种行为是出于内部优化原因。**
* 针对同一条消息，我们可能会生成 1 个以上的 `delivered` Webhook 事件，尤其是当最终用户使用多台设备时。
* **pricingModel**："PMP"—— 表示按消息计费。另请参阅 [whatsapp-message-pricing-updates](https://docs.ycloud.com/reference/whatsapp-message-pricing-updates.md)
* **pricingType**
  * **regular** — 表示该消息计费。
  * **free\_customer\_service** — 表示该消息免费，因为它是客服时间窗口内发送的效用消息模板或非模板消息。
  * **free\_entry\_point** — 表示该消息免费，因为它是免费入口点对话的一部分。

## 消息已读

在此情况下，您的 Webhook 端点接收到了消息 `read` 事件：

* 消息 `status` 为 `read`，表示消息已被收件人读取。

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "read",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "readTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'
```

### 响应

在持久化接收该事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

* 如果收件人关闭了已读回执，您将不会收到消息 `read` 回执。

## 消息发送失败

在此情况下，您的 Webhook 端点接收到了消息 `failed` 事件：

* 消息 `status` 为 `failed`。
* 包含 `errroCode`、`errorMessage` 和 `whatsappApiError`。

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "status": "failed",
    "errorCode": "100",
    "errorMessage": "Parameter Invalid",
    "whatsappApiError": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": "100",
      "fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Parameter Invalid"
      }
    },
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'
```

### 响应

在持久化接收该事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

* 这些事件旨在向您通知之前发送给客户的出站消息的状态变更。
* 消息发送失败的原因通常是消息请求参数无效、客户的电话号码未注册等。有关错误处理，请参阅 [WhatsApp Errors](https://docs.ycloud.com/zh/api-reference/guides/whatsapp-platform/whatsapp-error-code.md)。
* 如果我们曾尝试将此消息提交至 Meta 的 WhatsApp 平台，则会提供 `whatsappApiError` 以帮助您了解错误详情。另请参阅 [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)。
* 我们不会对失败的消息向您收费。

## 邮件投递更新

当邮件投递状态变更为 `delivered` 或 `failed` 时，使用 `email.delivery.updated`。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "customer@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}
```

### 响应

在持久化接收该事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

使用 `emailId` 和 `recipientAddress` 关联投递：该状态适用于此收件人。提供 `externalId` 时，可使用它来匹配您自己的记录。投递失败时请检查 `errorCode` 和 `errorMessage`。载荷属性为 `emailDelivery`，而非 `whatsappMessage`。

## SMS 投递更新

当 SMS 投递状态变更为 `delivered` 或 `undelivered` 时，使用 `sms.message.updated`。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "order_123"
  }
}
```

### 响应

在持久化接收该事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

通过 `sms.id` 识别 SMS 并读取 `sms.status`。投递失败时请检查 `errorCode`。SMS 使用 `undelivered` 表示失败投递回执；请勿将 WhatsApp `read` 状态模型应用于此事件。

## 语音投递更新

当语音消息状态变更为 `delivered` 或 `undelivered` 时，使用 `voice.message.updated`。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "verification_123"
  }
}
```

### 响应

在持久化接收该事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

通过 `voice.id` 识别语音消息并读取 `voice.status`。提供 `errorCode` 时请进行检查。此投递事件属于语音消息 API；它与 WhatsApp 通话生命周期事件相互独立。

## Messenger 出站已读快照

订阅 `messenger.message.updated` 以获取已保存的常规一对一出站快照。投递重试会保留 `Event.id`；从相同的源事实重新创建事件可能会产生新的 `Event.id`。请按 `messengerMessage.id` 关联更新。

### 提交与回执状态

`accepted` 表示 Meta 已接受提交，并不意味着消息已 `sent` 或 `delivered`。`rejected` 是明确的提交拒绝；`unknown` 是未确认的结果，绝不能视为失败。超时或出现 `unknown` 结果后，请勿自动重新提交消息。如有返回的消息 ID，请使用该 ID 检查其保存的状态，或联系支持人员。

快照会保留当前保存的事实，其中 `read` 优先于 `delivered`、`sent` 以及提交结果。迟到的回执不会降级该状态。您可能会收到重复的快照或遗漏中间状态。请将 `GET /v2/messenger/messages/{id}` 与 `from` 结合使用，或通过已确认的 Meta 消息 ID 进行检索，以对帐您当前保存的状态。

提交结果通知为尽力而为。请勿依赖针对每次同步发送结果都接收到 webhook。可选 ID、`errorCode` 以及回执时间在不可用时会被省略。在后续回执事实确立了更确定的状态后，已存储的提交错误可能仍然存在。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}
```

### 响应

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

Facebook Page ID 为 `from`，客户 PSID 为 `to`。此示例展示了保存的 `read` 状态，且未捏造缺失的 `sendTime` 或 `deliverTime`。`id` 是 YCloud 消息 ID，而 `metaMessageId` 则是提供商标识。

## Messenger 消息回应

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}
```

### 响应

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

使用 `pageId` 和 `psid` 来标识会话，并使用 `metaMessageId` 来标识目标消息。回应（reaction）属于互动行为，不会改变送达状态。目标消息可能没有本地 YCloud 消息记录。请保留源 `createTime`；可能会发生重复推送。在返回成功响应之前，请针对原始请求体验证 `YCloud-Signature`。

## Messenger 消息回应已撤回

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}
```

### 响应

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

移除与此 Page、客户 PSID 和目标 Meta 消息关联的回应。`unreact` 可以省略 `reaction` 和 `emoji`。不要强制要求本地消息 ID，也不要推断消息状态已发生变化。HTTP 推送重试会保留相同的事件 ID 和请求体；重复的源回调可能会生成新的事件 ID。在返回成功响应之前，请针对原始请求体验证 `YCloud-Signature`。


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