Messages API Status Callbacks

The Messages API sends status callbacks to your webhook URL to inform you whenever an event changes the state of a message — for example, when it’s submitted, delivered, or rejected.

These callbacks provide consistent visibility into the message lifecycle across all supported channels, including SMS, MMS, RCS, and apps: WhatsApp, Viber, and Facebook Messenger.

Every time a message status changes, Messages API sends a status callback to your configured webhook.
This callback includes key information such as the message UUID, channel, timestamp, delivery status, and where applicable, price and network metadata.

Different channels support different events and levels of insight. For example:

Callback Statuses

Read Status Callbacks

For OTT channels such as WhatsApp and Viber, the Messages API can send a read callback when the provider indicates that the end user has read the message on their device.

Submitted Status Callbacks

This status means that Messages API has passed a message on to a messaging provider.

Undeliverable Status Callbacks

This status means that Messages API was unable to connect to the messaging provider. This may be due to a messaging provider outage or other incident.

Rejected Status Callbacks

A message may be rejected for several reasons:

• Messages API cannot process the message (for example, invalid parameters or unsupported media).
• The provider rejects the message - for example, sending MMS to an unsupported country.
• The message’s time-to-live (TTL) expires before it can be delivered.

In these cases, a rejected callback is sent with an error object describing the failure.

Example Callbacks

SMS (Multi-part Message)

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2023-05-01T14:00:00.000Z",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "string",
  "channel": "sms",
  "destination": {
    "network_code": "12345"
  },
  "sms": {
    "total_count": "2"
  }
}

RCS (Rejected Request with SMS Failover)

{
  "message_uuid": "001",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:00.000Z",
  "status": "rejected",
  "channel": "rcs",
  "destination": {
    "network_code": "12345"
  },
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1260",
    "title": 1260,
    "detail": "Destination unreachable - The message could not be delivered to the phone number.",
    "instance": "abc102"
  },
  "workflow": {
    "id": "1001",
    "item_number": "1",
    "items_total": "2"
  }
}

Network Codes

Messages API includes a network_code in callbacks to identify the operator handling the message. Network codes are combinations of Mobile Country Codes (MCC) and Mobile Network Codes (MNC) and apply to SMS, RCS, and MMS, and represent the most accurate data available at the time of the status callback event.