Log inStart Free Trial
Meta Tech Provider

WhatsApp webhook statuses: sent, delivered, read and failed

Status webhooks report what happened to a message a business sent through the WhatsApp Cloud API. They arrive on the messages field with a statuses array instead of a messages array: sent (one check), delivered (two checks), read (two blue checks), played for voice messages, and failed with an errors array. Match statuses[].id to the wamid your send request returned.

easyCoexistence connects the WhatsApp Business app number you already use to Meta's Cloud API through Coexistence.

5

Status values Meta sends: sent, delivered, read, played (first play of voice messages) and failed.

3

Separate status webhooks one outgoing message can produce: sent, delivered and read.

v24.0

From this Graph API version the conversation object is omitted, except for messages in a free entry point window.

0

APIs for fetching past webhook data; Meta asks you to capture and store payloads as they arrive.

messages

The X-EC-Event header on a forwarded status: statuses travel inside messages events, under value.statuses.

Where do WhatsApp status webhooks arrive?

On the same messages field that carries what customers send, in the same object, entry and changes envelope. The difference is inside value: an inbound message has a messages array, a status has a statuses array. A handler that only reads value.messages drops every status without an error. metadata.phone_number_id says which of your numbers sent the message, and a contacts array with the customer's profile name, wa_id and BSUID comes along, except on failed statuses and on the sent status of group messages. This is Meta's example of a marketing template that left Meta's servers:

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"
        }
      ]
    }
  ]
}

What does each status value mean?

Each value matches a mark the customer would see in WhatsApp. A status counts as read only once it has been delivered, and when a customer receives a message while the chat is already open, Meta sends read without a delivered webhook first, as an internal optimization. So a tracker should accept read even when delivered never came, and should rank statuses rather than expect them one by one in a fixed sequence.

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.

Which fields does a status object carry?

Fewer than a message, and several are conditional. Meta's reference lists when each one is present:

  • id: the wamid of the message you sent, the key to match on.
  • status and timestamp: the value and the Unix time the webhook was triggered, as a string.
  • recipient_id: the phone number or group id, omitted when you sent to a BSUID and the number is unavailable.
  • recipient_user_id: the customer's BSUID, omitted on a failed status when you sent to a phone number.
  • recipient_type and recipient_participant_id: only for messages sent to a group.
  • biz_opaque_callback_data: only when you set it in the send request.
  • pricing: only on sent and on one of delivered or read. errors: only on failed.

How do you match a status to the message you sent?

By the wamid. The send request answers with messages[0].id, and every status for that message carries the same value in statuses[].id. Store it next to your own record when you send, then update the record when statuses arrive, keeping the highest status reached, so a late delivered does not overwrite read. A status whose wamid you do not know was sent by something else on the number, such as an automation, and can be ignored or logged.

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));
  }
}

What changes on a Coexistence number?

Statuses describe what was sent through the API: replies from your automations, messages your AI sent through an MCP connector, and anything your own code sent. What the owner types in the WhatsApp Business app reaches software differently, as smb_message_echoes, which Meta documents as the mirror of app-sent messages. Messages that came over in the one-time history import carry their own status inside the history webhook, with values such as delivered, read, played, pending and error.

Statuses go wherever the number's messages field goes. With a direct destination, Meta posts them straight to your endpoint, because messages is a field Meta lets a destination override. With automations on and a Forward URL set, they reach that URL as messages events.

How does your AI or automation learn whether a message was delivered?

Through your destination, not through the send. When an assistant calls send_template or send_message, the tool result carries the wamid and says Meta accepted the message; delivery is confirmed later, on the customer's device, and reported as a status. easyCoexistence keeps no status history to query, and no MCP tool reads statuses, so an agent that needs delivery confirmation should send through your system or read the statuses your Forward URL receives.

The same goes for automations: a run in the Runs tab shows the reply step done once Meta accepted the message, and a failure reported afterwards appears only as a failed status at your destination.

Common mistakes

  • Looking for a separate statuses field. Statuses come on messages, so a handler that reads only value.messages loses them without any error.
  • Requiring delivered before read. Meta skips the delivered webhook when the message is read the moment it arrives.
  • Treating the send response as delivery. A wamid means Meta accepted the request; a failure can follow minutes later as a failed status.
  • Keying customers on recipient_id alone. It is omitted when you sent to a BSUID and the phone number is unavailable; recipient_user_id carries the BSUID.
Doing this with EasyCoexistence

Statuses for what your automations, your AI or your code send go to your server: straight from Meta in direct mode, or forwarded to your Forward URL and signed with X-EC-Signature when automations are on, and they are not stored by default. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Do status webhooks include the text of the message?

No. A status carries the wamid, the status, the recipient, timestamps and, where they apply, pricing and errors. Keep your own copy of what you sent, keyed by the wamid, if you need to show it next to its status.

Can I fetch past statuses from Meta later?

No. Meta's webhook guide says there are no APIs for fetching historical webhook data, so a status your endpoint did not capture is gone once Meta stops retrying, after up to 7 days.

What is biz_opaque_callback_data for?

It is a string you set when sending, such as your own order or ticket id. Meta returns it in that message's statuses, so you can match a status to your record without looking up the wamid first.

Do I have to answer status webhooks with 200?

Yes, like any webhook POST. Meta treats any other response as a failed delivery and retries it, which is one of the ways the same status reaches you twice.

Keep reading

Ready to get started?

Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.

Start Free Trial

Verified on