接收事件
標準事件類型與載荷
每次投遞攜帶的統一信封，以及全部標準事件類型目錄。依端點用 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 即可發送引用回覆。若之後要回覆，請隨訊息一併存下。