登入開始免費試用
Meta Tech Provider

為何 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,並將失敗狀態傳送至您的伺服器,可直接傳送,亦可在啟用自動化時以已簽署的轉發形式傳送。

131047

收件人上次回覆已超過 24 小時;Meta 的解決辦法是改發訊息範本。

131049

為維持生態系統的參與度而未送達;重發推廣訊息範本前,請至少等待 24 小時。

131050

收件人已選擇停止接收該企業的推廣訊息;Meta 表示不應重試。

No contacts

失敗狀態不含 contacts 陣列,因此請透過 statuses.id 將失敗與原訊息對應。

Delivered

Meta 的收費方式:訊息於送達時計費,而非發送時計費。

失敗狀態是什麼樣子?

與任何狀態相同,但多了 errors。缺少 contacts 陣列;若訊息是發送到電話號碼,則省略 recipient_user_id;也沒有 pricing 物件。title 與 message 內容相同,error_data.details 會以一句話說明原因,href 則指向 Meta 的錯誤代碼列表。以下是 Meta 提供的官方示例,一則推廣訊息範本因每位用戶上限而被停止:

Meta's example: a message that failed with 131049
{
  "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 的錯誤代碼參考:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

處理程式應如何應對各類失敗?

在任何重試之前,先把代碼歸類為下一步行動。一律重試會把推廣退訂變成重複失敗,甚至延長封鎖時間;而捨棄暫時性錯誤,則會遺失一分鐘後本可成功送達的訊息。

  • 採用退避重試: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 已接受該訊息。
使用 EasyCoexistence 完成這項設定

當自動化的回覆在發送時被拒絕,執行紀錄會顯示 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,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用

驗證日期