WhatsApp API 訊息未能送達:按次序列出的七個原因
已接受的 WhatsApp API 訊息不等於已送達:Meta 會稍後透過狀態 webhook 回報結果,即已發送、已送達、已讀或失敗,並附上錯誤代碼。請按次序檢查:失敗狀態及其代碼、24 小時窗口(131047)、付款方式(131042)、範本(132001、132015)、收件人(131026、131049、131050),然後是號碼的限制與連接。
easyCoexistence 全天候監察每個已連接號碼,當 Meta 停止送達、斷開連接或降低質素時,會向您發送電郵,並會原封不動地把 Meta 的狀態 webhook 轉發至您的系統。
sent(一個勾號)、delivered(兩個勾號)、read(兩個藍色勾號)及 failed(紅色錯誤三角形),即狀態 webhook 所回報的狀態。
距離收件人上次回覆已超過 24 小時;Meta 建議改為發送範本。
無法送達:號碼未使用 WhatsApp、收件人未接受新條款,或其 WhatsApp 版本過舊。
WhatsApp 在放棄前重試未能送達的實用或推廣範本的預設時間;認證範本的預設時間為 10 分鐘。
同時用於 WhatsApp Business 應用程式及 Cloud API 的號碼,其吞吐量是固定的。
為什麼已接受的訊息仍未送達?
因為 API 的回應與送達屬於兩個獨立事件。發送時,Meta 一經接受請求便會返回訊息 ID;訊息能否抵達客戶手機,則稍後在 messages 欄位的狀態 webhook 中回報。sent 代表已離開 Meta 的伺服器(一個勾號);delivered 代表已抵達裝置(兩個勾號);read 代表已被開啟(兩個藍色勾號);failed 代表無法發送或送達,並透過 errors 陣列向您顯示,包括 code、title 及 error_data.details。因此,第一步永遠不是猜測:找出該訊息 ID 的失敗狀態,並讀取其代碼。若您沒有設定 webhook 目的地,系統便不會記錄任何內容。
按次序檢查,原因有哪些?
由新連接號碼上最常見的原因,到最罕見的原因排列。每一項都列出 Meta 的代碼,因此失敗狀態會告訴您屬於哪一類:
- 視窗已關閉:131047,客戶上次發訊後已超過 24 小時。自由格式訊息需要開啟中的視窗;請改為發送範本。
- 付款:131042,或範本被靜默丟棄。自 2026 年 10 月 1 日起,若未設定付款方式,服務訊息在每月使用量達 1,000 則後亦會停止發送。
- 範本:132001 未獲批准或語言錯誤,132000 變數數目錯誤,132012 格式錯誤,132015 已暫停,132016 已停用。
- 收件人:131026 未使用 WhatsApp、版本過舊或未接受條款;131050 已停止接收推廣訊息;131049 因維持良好互動而被暫緩;發送至美國號碼的推廣範本不會送達。
- 限制:131048 因垃圾訊息信號而受限,131056 向同一人發送過多訊息,130429 吞吐量,Coexistence 號碼為每秒 20 則訊息。
- 帳戶:131031 或 368,WhatsApp Business 帳戶因違反政策而受限或被停用。
- 連接:號碼已不再連結,例如在 14 天內未開啟 WhatsApp Business 應用程式之後。
如何處理收件人端的代碼?
需要分開處理,因為有些值得重試,有些則永遠不應重試。131050 代表該人選擇停止接收您的推廣訊息:Meta 建議不要重試,而 user_preferences webhook 會在對方停止或恢復接收時通知您。131049 是 Meta 為維持良好互動而暫緩推廣訊息,通常是對推廣範本設有每位用戶的上限:Meta 建議至少等待 24 小時才重新發送,因為提前重發只會再次得到相同錯誤。131026 涵蓋未使用 WhatsApp 的號碼、未接受 WhatsApp 最新條款的用戶,以及版本非常舊的應用程式;請先檢查號碼的格式及國家或地區代碼,然後透過其他渠道向客戶查詢。
WhatsApp 會嘗試送達多久?
直至訊息的存活時間(TTL)屆滿。當手機關機或超出網絡覆蓋範圍時,WhatsApp 會重試送達,而非即時失敗:實用及推廣範本的預設為 30 天,認證範本則為 10 分鐘。商家可按範本使用 message_send_ttl_seconds 縮短此時間,實用範本可設為 30 秒至 12 小時,認證範本則為 30 秒至 15 分鐘。在 TTL 內仍未能送達的訊息會被丟棄。因此,若訊息狀態為 sent 而數小時後仍無 delivered 狀態,通常是正在客戶手機上等待,而非遺失;對驗證碼及時間敏感的提示,應設定較短的 TTL,以免延遲送達造成混亂。
這對 AI 回覆及自動化有什麼影響?
先看運行記錄,再看狀態。在「運行」標籤中,「已略過」的運行表示未發送任何內容,並會說明原因:「距離客戶上次發訊已超過 24 小時」、「您最近已透過手機回覆此對話」或「此對話本小時的 AI 回覆上限已達到」。「已完成」的運行表示 Meta 已接受每則回覆,但這並非送達的證明。easyCoexistence 不會儲存訊息狀態:若您已啟用自動化並設定了轉發 URL,狀態會傳送至該 URL;在直接模式下,狀態則直接送達您自己的端點。若您使用 ChatGPT 或 Claude,可請您的 AI 執行 get_number_health:它會返回即時狀態、質素評級,以及最近 15 項監察事件,包括含有 Meta 代碼的 sending 區塊。
設定方法
- Find the statusLook up the message id in your webhook log and read the latest status: delivered, read, sent only, or failed with an error code.
- Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
- Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
- Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
- Check the numberAsk your AI to run get_number_health, or open the number in the dashboard, to see the connection and any sending block.
常見錯誤
- 對 131050 進行重試。該用戶已停止接收您的推廣訊息;再多次嘗試亦不會送達,只會增加負面信號。
- 把訊息 ID 當作已送達。Meta 先接受,之後才回報失敗,因此若工作流程在 ID 處停止,便會漏掉每則被拒的訊息。
- 一天後才發送自由格式回覆。客戶超過 24 小時未發訊後,只會接受範本。
- 未設定 webhook 目的地便運行。失敗狀態只會以 webhook 形式送達;若沒有目的地,訊息未能送達的原因便會遺失。
您的 AI 可透過 get_number_health,從 ChatGPT 或 Claude 檢查號碼狀況。每個已連接號碼每月 US$ 9 起,最低降至 US$ 0.75;號碼越多越便宜,首 3 天免費試用。
常見問題
為什麼訊息在數小時內只顯示一個勾號?
一個勾號代表 sent 狀態:Meta 已發出訊息,但手機尚未收到,通常是因為手機關機或離線。WhatsApp 會持續重試,直至範本的存活時間屆滿;實用及推廣範本的預設為 30 天。
為什麼回覆能送達,範本卻不能?
通常是 WhatsApp Business 帳戶的付款方式出現問題。Meta 會在號碼的每月免費額度內,即使沒有付款方式,仍送達服務訊息,但不會送達範本。請在「帳單及付款」中加入信用卡。
可以在 WhatsApp Business 應用程式中查看失敗的訊息嗎?
不可靠。在 Coexistence 號碼上,透過 API 發送的訊息會顯示在應用程式的對話串中,但訊息失敗的原因只會在狀態 webhook 的錯誤代碼中顯示。
Meta 會對未能送達的訊息收費嗎?
不會。Meta 只對已送達的訊息收費,而使用已暫停範本的嘗試亦不會被收費。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期