接收事件
標準事件類型同載荷
每次投遞帶嘅統一信封，同埋全部標準事件類型目錄。按端點用 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 就可以發引用回覆。如果之後要回覆，記得隨訊息一齊存低。