WhatsApp Webhook 狀態:已發送、已送達、已讀及失敗
狀態 webhook 會回報企業透過 WhatsApp Cloud API 發送的訊息發生了什麼事。它們會在 messages 欄位中送達,內容是 statuses 陣列,而非 messages 陣列:已發送(一個勾)、已送達(兩個勾)、已讀(兩個藍色勾)、語音訊息已播放,以及附有 errors 陣列的失敗。請將 statuses[].id 與發送請求回傳的 wamid 比對。
easyCoexistence 透過 Coexistence,將您已在使用的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API。
Meta 發送的狀態值包括 sent、delivered、read、played(語音訊息的首次播放)及 failed。
一則發出的訊息可產生以下獨立的狀態 webhook:sent、delivered 及 read。
從此 Graph API 版本起,對話物件會被省略,免費入口點視窗內的訊息除外。
沒有可提取過往 webhook 資料的 API;Meta 要求您在負載到達時即擷取並儲存。
轉發狀態時的 X-EC-Event 標頭:狀態會放在 messages 事件中,位於 value.statuses 之下。
WhatsApp 狀態 webhook 會送到哪裡?
它們與客戶的來信使用同一個 messages 欄位,同樣位於 entry 與 changes 的外層結構內。差異在 value 之中:收到的訊息帶有 messages 陣列,狀態則帶有 statuses 陣列。若處理程式只讀取 value.messages,便會在沒有任何錯誤的情況下遺漏所有狀態。metadata.phone_number_id 表示是哪一個號碼發出的訊息,並附有 contacts 陣列,內含客戶的個人檔案名稱、wa_id 及 BSUID,但失敗狀態與群組訊息的 sent 狀態除外。以下是 Meta 的範例,一則行銷範本已離開 Meta 伺服器:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}各個狀態值代表什麼?
每個值都對應客戶在 WhatsApp 中會看到的一個標記。狀態只有在訊息已送達後才算已讀;而當客戶在對話已開啟時收到訊息,Meta 會直接發送 read,不先發送 delivered webhook,這是內部的優化處理。因此,追蹤程式應接受沒有 delivered 的 read,並應依狀態的先後等級排序,而不是預期狀態會以固定順序逐一出現。
狀態物件包含哪些欄位?
欄位比訊息少,而且有些是有條件才出現的。以下是 Meta 參考文件中各欄位出現的條件:
- id:您發出之訊息的 wamid,即用來比對的關鍵。
- status 與 timestamp:狀態值,以及觸發 webhook 的 Unix 時間,以字串形式呈現。
recipient_id:電話號碼或群組 ID;若您以 BSUID 發送且號碼無法取得,則省略此欄位。recipient_user_id:客戶的 BSUID;若您以電話號碼發送,則在失敗狀態中省略此欄位。recipient_type與recipient_participant_id:僅用於發送至群組的訊息。biz_opaque_callback_data:僅在發送請求中設定此值時才會出現。- pricing:僅出現在 sent,以及 delivered 或 read 其中之一。errors:僅出現在 failed。
如何將狀態與您發出的訊息配對?
以 wamid 配對。發送請求會回傳 messages[0].id,同一則訊息的每個狀態都會在 statuses[].id 中帶有相同的值。發送時請將它與您自己的記錄一併儲存,之後狀態到達時再更新記錄,並保留已達到的最高狀態,這樣晚到的 delivered 就不會覆蓋 read。若某個狀態的 wamid 您並不認得,表示它是由同一號碼上的其他程式發出的,例如自動化流程,可以忽略或記錄下來。
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Coexistence 號碼有什麼不同?
狀態反映的是透過 API 發送的內容:您的自動化流程所發的回覆、您的 AI 透過 MCP 連接器發送的訊息,以及您自己的程式所發送的任何內容。擁有者在 WhatsApp Business 應用程式中輸入的訊息,會以不同方式傳送至軟件,名為 smb_message_echoes,Meta 將其記錄為應用程式所發訊息的鏡像。一次性歷史匯入的訊息,其狀態則內含於歷史 webhook 之中,狀態值包括 delivered、read、played、pending 及 error。
狀態會依該號碼的 messages 欄位設定送達。若為直接模式,Meta 會直接將狀態發送至您的端點,因為 messages 是 Meta 允許目的地覆寫的欄位。若開啟自動化並設定了轉發 URL,狀態則會以 messages 事件的形式送到該 URL。
您的 AI 或自動化流程如何得知訊息是否已送達?
透過您的目的地,而非透過發送動作。當助理呼叫 send_template 或 send_message 時,工具結果會包含 wamid,並表示 Meta 已接受該訊息;送達則是稍後在客戶的裝置上確認,並以狀態形式回報。easyCoexistence 沒有可供查詢的狀態記錄,也沒有 MCP 工具可讀取狀態,因此需要確認送達的代理,應透過您自己的系統發送,或讀取轉發 URL 收到的狀態。
自動化流程也是如此:在「Runs」分頁中,回覆步驟於 Meta 接受訊息後即顯示為已完成;之後才回報的失敗,只會以 failed 狀態出現在您的目的地。
常見錯誤
- 以為狀態有獨立的 statuses 欄位。狀態是透過 messages 傳送,因此只讀取 value.messages 的處理程式會在沒有任何錯誤的情況下遺漏狀態。
- 要求 read 之前必須先有 delivered。當訊息一到達就被讀取時,Meta 會略過 delivered webhook。
- 把發送回應當成已送達。wamid 只代表 Meta 已接受請求;失敗可能在數分鐘後才以 failed 狀態出現。
- 只以 recipient_id 識別客戶。若您以 BSUID 發送且電話號碼無法取得,此欄位會被省略;BSUID 則放在 recipient_user_id 中。
您的自動化流程、AI 或程式所發送訊息的狀態,會送到您的伺服器:直接模式下由 Meta 直接傳送,或在開啟自動化時,附帶 X-EC-Signature 簽署後轉發至您的轉發 URL;我們預設不儲存這些狀態。每個已連接號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,並提供前 3 天免費試用。
常見問題
狀態 webhook 會包含訊息的內文嗎?
不會。狀態包含 wamid、狀態值、收件人、時間戳記,以及(如適用的)定價與錯誤資訊。如需與狀態並列顯示,請自行保留一份發送內容的副本,並以 wamid 為鍵。
之後可以從 Meta 取回過往的狀態嗎?
不行。Meta 的 webhook 指南表示,沒有可提取歷史 webhook 資料的 API,因此若您的端點未曾擷取某個狀態,在 Meta 停止重試(最多 7 天)後,該狀態便無法再取得。
biz_opaque_callback_data 有什麼用途?
這是發送時您自行設定的字串,例如您的訂單或工單編號。Meta 會在該訊息的 statuses 中回傳此值,因此您無需先查詢 wamid,即可將狀態與您的記錄配對。
我是否必須以 200 回應狀態 webhook?
是的,與任何 webhook POST 相同。Meta 會將其他任何回應視為發送失敗並重試,這也是同一狀態會重複送達您的原因之一。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期