WhatsApp webhooks

Bird 会在 WhatsApp 活动发生时实时推送到你的端点，无需轮询。你可以在 Webhooks 页面或通过 POST /v1/webhooks 订阅。Webhooks 指南涵盖端点、签名验证和重试。

可订阅的事件

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

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

事件信封

每个 WhatsApp 事件都使用标准的 webhook 信封：一个 type、一个 timestamp，以及一个特定于类型的 data 对象。

{
  "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（在 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} 回读消息以查看其费用。

后续步骤

• 消息状态 webhooks：投递与失败载荷
• 入站消息 webhooks：whatsapp.received 载荷
• Reaction webhooks：whatsapp.reacted 载荷
• Webhooks 指南：端点、签名、重试及完整事件目录