接收事件
标准事件类型与载荷
每次投递携带的统一信封，以及全部标准事件类型目录。按端点用 subscribed_events 订阅（使用下方的精确名称），或用 ["*"] 订阅全部。信封固定为 id / type / provider / account_id / occurred_at / data；data 的结构取决于 type。
事件载荷
{
"id": "evt_2f9c1a4b7e",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:34:56Z",
"data": {
"account": { "provider_account_ref": "8613800138000" },
"conversation": { "id": "8613912345678", "type": "user", "title": "Jordan Lee" },
"sender": { "id": "8613912345678", "name": "Jordan Lee", "type": "user" },
"message": {
"id": "wamid.HBgM",
"text": "Hi - is my order shipped yet?",
"direction": "inbound",
"sent_at": "2026-06-08T12:34:55Z"
}
}
}标准事件类型
- message.received
账号收到一条入站消息。
- message.updated
一条已投递的消息被编辑。
- message.deleted
一条消息被删除或撤回。
- message.read
已读回执——对方已读某条消息。
- message.reaction
某条消息被添加或移除了表态（reaction）。
- message.delivered
一条消息已送达对方设备。
- conversation.updated
会话级设置发生变化——静音 / 取消静音、归档、置顶或标记已读。
- conversation.deleted
一个会话被删除。
- conversation.cleared
一个会话的聊天记录被清空。
- conversation.history
WhatsApp 在启动或重连后同步了某个会话的近期历史消息。
- group.updated
群组元信息变化——名称、成员或设置。
- group.join_request
有人申请加入开启了入群审批的群。推送为尽力而为——请以轮询「列出入群申请」为准。
- account.status.updated
账号的运行时 / 连接状态发生变化。
- account.started
账号运行时已连接，可以收发消息。
- account.history.synced
一次 WhatsApp 历史同步批次已结束；data.summary 给出已投递的会话与消息数量。
- account.auth.required
账号需要（重新）认证——验证码、扫码或两步验证。
- account.auth.succeeded
认证完成，账号已上线。
- account.auth.failed
一次认证尝试失败。
备注
- 对于媒体消息，data.message.attachments[] 携带临时签名的 OSS url，以及 type、mimetype、size。
- subscribed_events 必须填上面的精确事件名或 ["*"]。创建或更新端点时，未知名称会被拒绝。
- 并非每个 provider 都发出全部事件，部分载荷字段也有差异——按 provider 的差异见「Webhook 标准事件差异」矩阵。
- message.read 与 message.delivered 携带精确的回执范围：data.message.ids 列出本次回执覆盖的全部消息，read_at / delivered_at 给出渠道上报的时间。
- WhatsApp 入站消息携带 data.message.reply_token——把它原样放入 POST /v1/messages 的 reply_to.reply_token 即可发送引用回复。若以后要回复，请随消息一起存下来。