WhatsApp 消息状态 webhook
投递事件
whatsapp.accepted、whatsapp.sent、whatsapp.delivered 和 whatsapp.read 仅携带每个消息事件都携带的字段。生命周期事件说明了每个事件的含义以及何时会跳过 whatsapp.delivered。
代码示例
{
"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。请参阅失败事件了解两者的区别。当报告失败 WhatsApp 时，description 是 WhatsApp 自身的解释。一条服务消息如果在接受和分发之间客户服务窗口已关闭，则会如下失败：
代码示例
{
"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"
}将入站消息标记为已读会在消息的时间线中记录 whatsapp.read，但不会触发 webhook。
后续步骤
- 入站消息 webhook：联系人向您发送消息时的 whatsapp.received 载荷
- 回应 webhook：联系人的回应会单独送达
- 消息状态事件：通过 API 回读消息的时间线