message.status

API reference/Webhook events

Copy page

message.status

Sent with your delivery and read receipts: each time an outgoing message is delivered, read or fails. Use it to show ticks in your own tools, or to retry a send that failed. The sent status comes as message.sent. A late or repeated status from WhatsApp sends nothing.

Called Message status changed in the app. Part of the plan feature webhooks.messages. To subscribe over the API, the key needs messages:read.

Delivered

{
  "id": "evt_15572b9fc8c1f0f2892d5db95b252814",
  "type": "message.status",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:30:16.116Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "message_id": "8c2e4f6a-1d3b-4a5c-9e7f-2b4d6f8a0c1e",
    "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
    "broadcast_id": null,
    "status": "delivered",
    "at": "2026-10-14T09:30:15.902Z",
    "error": null
  }
}

Headers

webhook-id

The delivery’s ID, the same on every try.

webhook-timestamp

When this try was sent, in Unix seconds.

webhook-signature

v1, and an HMAC-SHA256 of the request.

How delivery and retries work

How a message’s status moves

1. pendingAnswer to Send a message
2. sentmessage.sent
3. deliveredmessage.status
4. readmessage.status

failedmessage.statusCan replace any status, once. After that the message stays failed, and error says why.

Data

What’s in data. Every event wraps it in the same envelope.

message_id string · uuid

contact_id string · uuid

number_id string · uuid · nullable

broadcast_id string · uuid · nullable

The broadcast the message belongs to, or null.

status string

The status the message moved to. The sent status comes as message.sent. More values may be added.

One of sent delivered read failed.

at string · date-time

When WhatsApp reported the status. Order events by this, not by when they arrive.

error object · nullable

Why the message failed.

Show 2 child attributesHide child attributes

error.code integer

WhatsApp’s error code, or 0 when it isn’t known.

error.message string

Handling it

• Answer with any 2xx within 10 seconds. Do the work after.
• Check the signature first. Verify webhooks has the code.
• Subscribe with POST /v1/webhooks, events: ["message.status"].