---
title: "WhatsApp webhooks"
description: "WhatsApp 可以推送到你端点的 webhook 事件 Bird、每个事件的信封结构，以及消息事件始终携带的字段。"
canonical: "https://bird.com/zh-sg/wendang/guides/whatsapp/webhooks"
---

# WhatsApp webhooks

Bird 会在 WhatsApp 活动发生时实时推送到你的端点，无需轮询。你可以在 [**Webhooks**](https://bird.com/dashboard/w/webhooks) 页面或通过 [`POST /v1/webhooks`](/docs/api/reference/create-webhook) 订阅。[Webhooks 指南](/docs/guides/webhooks)涵盖端点、签名验证和重试。

## 可订阅的事件

每个事件都链接到其载荷。

| 事件                                                                                                | 触发条件                              |
| --------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [`whatsapp.accepted`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)                | Bird 接受一个出站发送请求             |
| [`whatsapp.sent`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)                    | Bird 将消息交给 WhatsApp 网络         |
| [`whatsapp.delivered`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)               | WhatsApp 确认消息已投递到收件人的设备 |
| [`whatsapp.read`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)                    | 收件人打开了消息                      |
| [`whatsapp.failed`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)                  | 消息投递失败                          |
| [`whatsapp.rejected`](/docs/guides/whatsapp/webhooks/message-status#delivery-events)                | Bird 在发送前拒绝了消息               |
| [`whatsapp.received`](/docs/guides/whatsapp/webhooks/messages)                                      | 联系人向你发送了一条消息              |
| [`whatsapp.reacted`](/docs/guides/whatsapp/webhooks/reactions)                                      | 联系人添加、更改或移除了一个回应      |
| [`whatsapp_suppression.created`](/docs/guides/whatsapp/webhooks/suppressions)                       | 你的工作区中产生了一条抑制记录        |
| [`whatsapp.group.join_request_created`](/docs/guides/whatsapp/webhooks/groups#join-request-created) | 有人申请加入群组                      |
| [`whatsapp.group.join_request_revoked`](/docs/guides/whatsapp/webhooks/groups#join-request-revoked) | 有人取消了加入群组的申请              |

事件类型列表是开放的：新类型可能会随时间增加，因此请将无法识别的值视为未来事件，而非错误。

## 事件信封

每个 WhatsApp 事件都使用标准的 [webhook 信封](/docs/guides/webhooks)：一个 `type`、一个 `timestamp`，以及一个特定于类型的 `data` 对象。

```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 消息的 webhook 载荷包含 `whatsapp_id`、`workspace_id`、`direction`、`from`、`to`、`tags` 和 `metadata`。回应、抑制和群组事件与消息无关，各自有独立的结构，详见其页面。

- **地址**：`from` 和 `to` 可以包含一个 E.164 `phone_number`、一个 Meta [业务范围用户 ID](/docs/guides/whatsapp/business-scoped-user-ids)（在 `bsuid` 中），或两者兼有。从 WhatsApp 用户收到的消息还会携带其公开的个人资料，在 `username` 和 `display_name` 中。
- **`tags` 和 `metadata`** 在发送时未携带值的情况下为 `null`。
- **`in_reply_to_message_id`** 出现在以回复形式发送的消息的每个出站事件中，从 `whatsapp.accepted` 到 `whatsapp.read`、`whatsapp.failed` 或 `whatsapp.rejected`，标明其所回复的消息。

事件载荷不包含费用信息。使用 [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) 回读消息以查看其费用。

## 后续步骤

- [消息状态 webhooks](/docs/guides/whatsapp/webhooks/message-status)：投递与失败载荷
- [入站消息 webhooks](/docs/guides/whatsapp/webhooks/messages)：`whatsapp.received` 载荷
- [Reaction webhooks](/docs/guides/whatsapp/webhooks/reactions)：`whatsapp.reacted` 载荷
- [Webhooks 指南](/docs/guides/webhooks)：端点、签名、重试及完整事件目录

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