WhatsApp Status Callbacks

When you send a WhatsApp message using the Vonage Messages API, Vonage delivers status callbacks to your configured webhook URL each time the state of a message changes — for example, when it is sent, delivered, or read.

Vonage receives status updates from Meta (WhatsApp's underlying provider) and translates them into a consistent callback format before forwarding them to your application. This means the payload your webhook receives may differ from the raw Meta webhook payload.

For a general overview of status callbacks across all channels, see Messages API Status Callbacks.

Message Status Callbacks

Vonage sends a status callback to your webhook URL whenever a WhatsApp message transitions to a new state. The following statuses are supported:

Status	Description
`submitted`	Vonage has accepted the message and passed it to WhatsApp.
`delivered`	The message has been delivered to the recipient's device.
`read`	The recipient has opened the message (requires read receipts to be enabled).
`rejected`	The message was rejected by Vonage or WhatsApp. An `error` object is included in the payload.
`undeliverable`	Vonage was unable to connect to WhatsApp to deliver the message.

Status Callback Payload

The following example shows the full set of fields that can appear in a WhatsApp status callback. Not every field is present on every callback — for example, error is only included for rejected or undeliverable statuses, workflow is only included when the message was sent as part of a workflow, and profile / whatsapp.recipient are only included when available from WhatsApp:

{
  "to": "447700900001",
  "from": "447700900001",
  "channel": "whatsapp",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0"
  },
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "whatsapp": {
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "waba_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "conversation": {
      "id": "1234567890",
      "origin": {
        "type": "marketing"
      }
    }
  },
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "timestamp": "2025-02-03T12:14:25Z",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": "1000",
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  },
  "client_ref": "abc123",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

For a full list of status fields, see the Status Callback Fields section of the Messages API reference.

Error Callbacks

When a message is rejected or undeliverable, the callback includes an error object:

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "rejected",
  "channel": "whatsapp",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": 1000,
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  }
}

Inbound Message Callbacks

When a WhatsApp user sends a message to your WhatsApp Business number, Vonage forwards the message to your inbound webhook URL.

You must configure an inbound webhook URL in your Vonage API Dashboard or via the Application API to receive inbound messages.

Inbound Message Payload

The following is an example of an inbound text message callback:

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "context_status": "available",
  "context": {
    "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
    "message_from": "447700900000"
  },
  "provider_message": "Message delivered",
  "message_type": "text",
  "text": "Hello from Vonage!",
  "whatsapp": {
    "sender": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "referral": {
      "body": "Check out our new product offering",
      "headline": "New Products!",
      "source_id": "212731241638144",
      "source_type": "post",
      "source_url": "https://fb.me/2ZulEu42P",
      "media_type": "image",
      "image_url": "https://example.com/image.jpg",
      "video_url": "https://example.com/video.mp4",
      "thumbnail_url": "https://example.com/thumbnail.jpg",
      "ctwa_clid": "1234567890"
    }
  },
  "_self": {
    "href": "https://api-eu.vonage.com/v1/messages/aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
  }
}

For a full list of inbound message fields, see the Inbound Message Fields section of the Messages API reference.

Deprecated Fields

The following fields are planned for deprecation:

Field	Notes
`whatsapp.conversation`	Will be deprecated for webhooks API version 23.0 and above, except for free entry point conversations.
`pricing.billable`	Will be deprecated in a future release. Use `whatsapp.pricing` instead.
`usage.price`	Will be set to `"0"` from July 1, 2025 under the Per-Message Pricing (PMP) model.

Further Information

Messages API Status Callbacks