# WhatsApp 消息状态 webhook

出站消息的每次[状态](/docs/guides/whatsapp/events/message-status)变更都可以在发生时推送到您的端点。每个载荷使用 [WhatsApp 事件信封](/docs/guides/whatsapp/webhooks#the-event-envelope)，并携带[每个消息事件都携带的字段](/docs/guides/whatsapp/webhooks#fields-every-message-event-carries)。

## 投递事件

`whatsapp.accepted`、`whatsapp.sent`、`whatsapp.delivered` 和 `whatsapp.read` 仅携带每个消息事件都携带的字段。[生命周期事件](/docs/guides/whatsapp/events/message-status#lifecycle-events)说明了每个事件的含义以及何时会跳过 `whatsapp.delivered`。

```json
{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}
```

`whatsapp.failed` 和 `whatsapp.rejected` 还携带一个 `error` 对象，其中包含一个稳定的 Bird `code`、一个人类可读的 `description`、一个可选的 `meta_error_code`，以及 `occurred_at`。请参阅[失败事件](/docs/guides/whatsapp/events/message-status#failure-events)了解两者的区别。当报告失败 WhatsApp 时，`description` 是 WhatsApp 自身的解释。一条服务消息如果在接受和分发之间客户服务窗口已关闭，则会如下失败：

```json
{
  "data": {
    "direction": "outbound",
    "error": {
      "code": "service_window_expired",
      "description": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "meta_error_code": "131047",
      "occurred_at": "2026-07-23T14:51:40.201Z"
    },
    "from": { "phone_number": "+13124495569" },
    "metadata": null,
    "tags": null,
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:40.201Z",
  "type": "whatsapp.failed"
}
```

[将入站消息标记为已读](/docs/guides/whatsapp/mark-message-as-read)会在消息的时间线中记录 `whatsapp.read`，但不会触发 webhook。

## 后续步骤

- [入站消息 webhook](/docs/guides/whatsapp/webhooks/messages)：联系人向您发送消息时的 `whatsapp.received` 载荷
- [回应 webhook](/docs/guides/whatsapp/webhooks/reactions)：联系人的回应会单独送达
- [消息状态事件](/docs/guides/whatsapp/events/message-status)：通过 API 回读消息的时间线

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)