登入開始免費試用
Meta Tech Provider

WhatsApp Webhook 狀態:已發送、已送達、已讀及失敗

狀態 webhook 會回報企業透過 WhatsApp Cloud API 發送的訊息發生了什麼事。它們會在 messages 欄位中送達,內容是 statuses 陣列,而非 messages 陣列:已發送(一個勾)、已送達(兩個勾)、已讀(兩個藍色勾)、語音訊息已播放,以及附有 errors 陣列的失敗。請將 statuses[].id 與發送請求回傳的 wamid 比對。

easyCoexistence 透過 Coexistence,將您已在使用的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API。

5

Meta 發送的狀態值包括 sent、delivered、read、played(語音訊息的首次播放)及 failed。

3

一則發出的訊息可產生以下獨立的狀態 webhook:sent、delivered 及 read。

v24.0

從此 Graph API 版本起,對話物件會被省略,免費入口點視窗內的訊息除外。

0

沒有可提取過往 webhook 資料的 API;Meta 要求您在負載到達時即擷取並儲存。

messages

轉發狀態時的 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 伺服器:

Meta's example: a marketing message with status sent
{
  "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,並應依狀態的先後等級排序,而不是預期狀態會以固定順序逐一出現。

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

狀態物件包含哪些欄位?

欄位比訊息少,而且有些是有條件才出現的。以下是 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 status webhooks to your sends (Node.js)
// 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 中。
使用 EasyCoexistence 完成這項設定

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

開始免費試用

驗證日期