Events

Delivered on the endpoint you registered in Webhooks, which is also where signature verification, the envelope and retry behaviour are described. This page is only which events WhatsApp produces.

Event	Fires when
`conversation.created`	a thread is opened — including when no assistant will answer it
`message.received`	a customer’s message is accepted — including media, before transcription finishes
`message.sent`	an outbound message is accepted by Meta — AI, the merchant’s staff, or your own API call
`message.delivered`	it reached the recipient’s device
`message.read`	the recipient opened it
`message.failed`	Meta could not deliver it. Carries their code and title
`message.deleted`	the sender revoked a message. Carries the revoked id
`handoff.requested`	the assistant stopped and a person is needed. Time-sensitive
`template.status_changed`	a template was approved, rejected or paused
`conversation.completed`	a thread reached a terminal state
`lead.hot` ^preview	a message showed buying intent
`lead.verification_requested` ^preview	a lead asked to be verified

GET /api/v2/webhooks/catalogue/ returns the live list, including the resource each event carries and the scope it needs. Your code probably wants that rather than this table.

message.received fires for media before the voice note is transcribed, so channel.media.transcription may be empty on arrival. Render the message immediately rather than waiting — a customer’s voice note appearing thirty seconds late looks like a broken inbox. Fetch the file with GET /media/{ref}/.

Delivery status

The ticks you draw beside a message, and the per-recipient outcome a broadcast report is built from.

{
  "type": "message.delivered",
  "tenant_ref": "merchant_8812",
  "data": { "object": {
    "object": "message_status",
    "channel": { "name": "whatsapp", "message_id": "wamid.HBg…" },
    "conversation": "…",
    "status": "delivered",
    "recipient": "919876543210",
    "at": "2026-09-07T10:12:04Z",
    "pricing": { "billable": true, "category": "marketing", "model": "PMP" }
  } }
}

pricing.category is what a broadcast cost estimate multiplies, and this is the only place it is available. A failure carries Meta’s own diagnosis rather than ours:

"error": { "code": "131047", "title": "Re-engagement message",
           "detail": "More than 24 hours have passed…" }

sent is not re-emitted as a status. message.sent already fired when we handed the message to Meta. Emitting the same fact twice under two names is how a delivery report ends up counting every message once too often.The states you receive are delivered, read and failed — and they can arrive out of order, or not at all. A customer with read receipts disabled never produces message.read, which is not a failure and not something to wait for.

Template approval

Approval takes hours, so it arrives long after the POST that created the template.

{
  "type": "template.status_changed",
  "data": { "object": {
    "object": "template",
    "name": "order_update",
    "language": "en_US",
    "status": "REJECTED",
    "category": "MARKETING",
    "rejected_reason": "INVALID_FORMAT"
  } }
}

Meta sends this against the WhatsApp Business Account rather than a phone number, so it arrives for the merchant that owns the WABA. See Templates.

Get started

Provisioning

Channels

Operating

Delivery status

Template approval

​Delivery status

​Template approval

Delivery status

Template approval