為何 WhatsApp 訊息發送失敗:讀取失敗狀態及其錯誤
失敗狀態 Webhook 代表 Meta 無法發送或送達企業透過 API 發出的訊息。它會透過 messages 欄位送達,狀態為 failed,並附有 errors 陣列,其中包含 code、title、message、error_data.details 與 href。代碼說明原因:131047 窗口已關閉、131026 無法送達、131049 推廣訊息達上限、131050 收件人已停止接收推廣訊息、131042 付款問題。
easyCoexistence 透過 Coexistence 將您的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,並將失敗狀態傳送至您的伺服器,可直接傳送,亦可在啟用自動化時以已簽署的轉發形式傳送。
收件人上次回覆已超過 24 小時;Meta 的解決辦法是改發訊息範本。
為維持生態系統的參與度而未送達;重發推廣訊息範本前,請至少等待 24 小時。
收件人已選擇停止接收該企業的推廣訊息;Meta 表示不應重試。
失敗狀態不含 contacts 陣列,因此請透過 statuses.id 將失敗與原訊息對應。
Meta 的收費方式:訊息於送達時計費,而非發送時計費。
失敗狀態是什麼樣子?
與任何狀態相同,但多了 errors。缺少 contacts 陣列;若訊息是發送到電話號碼,則省略 recipient_user_id;也沒有 pricing 物件。title 與 message 內容相同,error_data.details 會以一句話說明原因,href 則指向 Meta 的錯誤代碼列表。以下是 Meta 提供的官方示例,一則推廣訊息範本因每位用戶上限而被停止:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
},
"field": "messages"
}
]
}
]
}最常見的錯誤代碼有哪些,各代表什麼?
Meta 會在發送回應、失敗狀態中回傳錯誤,或兩者皆有,因此同一代碼可能以任一方式送達,您的處理程式應兩處都讀取。以下代碼解釋了大多數未能送達的訊息,附有 Meta 的原因說明及首要處理步驟;完整列表請參閱 Meta 的錯誤代碼參考:
處理程式應如何應對各類失敗?
在任何重試之前,先把代碼歸類為下一步行動。一律重試會把推廣退訂變成重複失敗,甚至延長封鎖時間;而捨棄暫時性錯誤,則會遺失一分鐘後本可成功送達的訊息。
- 採用退避重試:131000 未知錯誤、131016 服務不可用、130429 已達吞吐量上限。
- 先行等待:131049,至少 24 小時,因為過早重試可能使該用戶再被封鎖最多 24 小時。
- 改為換發訊息:131047 需要已核准的範本,因為 24 小時窗口已關閉。
- 停止對該客戶發送:131050,直至收到
user_preferences的恢復通知。 - 修正帳戶或內容問題:131042 付款、131031 帳戶受限、131053 媒體。
哪些失敗只會以失敗狀態出現?
這些是 Meta 在接受請求之後才作出判定的情況。發送時會回傳 wamid,拒絕結果則稍後在此 Webhook 出現。Meta 不會向美國電話號碼(+1 加美國區號)的 WhatsApp 用戶送達推廣訊息範本;若客戶已停止接收推廣訊息,推廣範本會先被處理,然後以 131050 回報為失敗;每位用戶的推廣上限亦以相同方式回報 131049。
若該號碼沒有 Webhook 目的地,這些失敗便無處可見,訊息看起來只是已發送。客戶未收到訊息時的完整檢查順序,請參閱「WhatsApp API 訊息未送達」一頁。
Coexistence 號碼有何不同?
有兩點重要。第一,24 小時窗口只約束 API。Meta 的 Coexistence 指南指出,從 WhatsApp Business 應用程式發出的訊息不受客戶服務窗口限制,因此出現 131047 後,擁有者仍可用手機回覆該客戶,而您的系統則發送已核准的範本。
第二,吞吐量是固定的。同時在應用程式與 API 中使用的號碼,每秒最多只能發送 20 則訊息,超出則回傳 130429。其餘一切與任何 Cloud API 號碼相同:相同欄位、相同 errors 陣列、相同代碼。
自動化與您的 AI 如何看待失敗?
視乎 Meta 何時作出拒絕。發送時的拒絕(如 131047)會令自動化的步驟失敗:「Runs」分頁會顯示「失敗」及 Meta 的訊息,擁有者會收到電郵,以便親自回覆該客戶。自動化在發送自由格式回覆前亦會檢查窗口,若已關閉則以 window_closed 略過,而不會嘗試發送。
Meta 事後才回報的失敗,會以 failed 狀態送達您的轉發 URL 或直接目的地,而執行紀錄維持不變。若 AI 透過 MCP 連接器發送了範本,它會看到 wamid 及「sent: true」;請向您的系統查詢該 wamid 的狀態,或在大量訊息失敗時,請助手執行 get_number_health。
常見錯誤
- 以迴圈方式重試 131050。客戶已停止接收推廣訊息,因此每次嘗試都會以相同方式失敗,直至客戶恢復接收。
- 在數小時內重發 131049 推廣訊息範本。Meta 要求至少等待 24 小時,過早重試可能使該用戶再被封鎖最多 24 小時。
- 只記錄 title。error_data.details 載有具體原因,因此應將代碼與詳情連同 wamid 一併儲存。
- 在沒有 Webhook 目的地的情況下運作,並以發送回應判斷送達,但發送回應只說明 Meta 已接受該訊息。
當自動化的回覆在發送時被拒絕,執行紀錄會顯示 Meta 的錯誤,您也會收到電郵;每個號碼均 24/7 受監察,以偵測斷線及質量下降。每個已連接號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,首 3 天免費試用。
常見問題
Meta 會就失敗的訊息收費嗎?
Meta 的定價頁面指出,只就成功送達的訊息收費,而非只是發送的訊息。失敗狀態不包含 pricing 物件。費用由企業自己的 WhatsApp Business Account 承擔;easyCoexistence 從不加價。
131026 是否代表客戶封鎖了該企業?
Meta 對 131026 的列表還列出其他原因:該號碼不在 WhatsApp 上、收件人尚未接受最新條款,或其 WhatsApp 版本過舊。Meta 建議透過其他渠道向客戶查證這些情況。
為何部分失敗會有 recipient_user_id,部分則沒有?
若訊息是發送到電話號碼,Meta 會在失敗狀態中省略該欄位。若您是發送到客戶的 BSUID,失敗狀態便會包含該欄位,而 recipient_id 則可能是缺少的那一個。
訊息送達後還會失敗嗎?
Meta 的參考資料將 failed 定義為發送或送達失敗。訊息一旦抵達裝置,您可預期的後續狀態為已讀,語音訊息則為已播放。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期