登入開始免費試用
Meta Tech Provider

WhatsApp API 訊息未能送達:按次序列出的七個原因

已接受的 WhatsApp API 訊息不等於已送達:Meta 會稍後透過狀態 webhook 回報結果,即已發送、已送達、已讀或失敗,並附上錯誤代碼。請按次序檢查:失敗狀態及其代碼、24 小時窗口(131047)、付款方式(131042)、範本(132001、132015)、收件人(131026、131049、131050),然後是號碼的限制與連接。

easyCoexistence 全天候監察每個已連接號碼,當 Meta 停止送達、斷開連接或降低質素時,會向您發送電郵,並會原封不動地把 Meta 的狀態 webhook 轉發至您的系統。

4 statuses

sent(一個勾號)、delivered(兩個勾號)、read(兩個藍色勾號)及 failed(紅色錯誤三角形),即狀態 webhook 所回報的狀態。

131047

距離收件人上次回覆已超過 24 小時;Meta 建議改為發送範本。

131026

無法送達:號碼未使用 WhatsApp、收件人未接受新條款,或其 WhatsApp 版本過舊。

30 days

WhatsApp 在放棄前重試未能送達的實用或推廣範本的預設時間;認證範本的預設時間為 10 分鐘。

20 mps

同時用於 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 區塊。

設定方法

  1. 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.
  2. Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
  3. Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
  4. Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
  5. 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 形式送達;若沒有目的地,訊息未能送達的原因便會遺失。
使用 EasyCoexistence 完成這項設定

您的 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,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用

驗證日期