Sending a Message with Failover

When sending messages with the Vonage Messages API, they may be rejected. In a single API request, failover messages can be defined to be sent in their place. For example, if a customer device does not support your primary channel, such as RCS, they will continue to receive your messages through alternative channels.

This guide walks you through how to configure message failover in your request and how to monitor delivery status through callbacks.

Sending a Request With Message Failover

In this example, an RCS text message is sent first, followed by an SMS message if that message fails. The structure for the request is the same as sending a standard message for the primary channel; the failover message is then defined in a failover array as follows:

{
  "to": "447700900000",
  "from": "Vonage",
  "channel": "rcs",
  "message_type": "image",
  "image": {
    "url": "https://example.com/image.jpg",
    "caption": "This is an image sent via RCS using the Vonage Messages API."
  },
  "failover": [
    {
      "to": "447700900000",
      "from": "447700900001",
      "channel": "sms",
      "message_type": "text",
      "text": "This is an SMS sent using the Vonage Messages API."
    }
  ]
}

You can define as many failover channels as required; the failover messages will be sent in the order they are defined in the array.

Each message within the failover array requires its own channel, message_type from, to, and message content; more information about each channel and its required parameters can be found in the API specification. You should also ensure that the message content is adapted to the capabilities of each fallback channel.

Example requests using cURL and the Vonage SDKs can be found on the Send a Message With Failover code snippet page.

Monitoring Status and Callbacks

When your message is sent, the API returns status callbacks to your webhook URL. These track the progress and outcome of each message in the failover sequence. An example flow for RCS failing over to SMS would be:

  1. RCS Submitted → Message sent to primary channel (in this case RCS).
  2. RCS Rejected → Message delivery failed.
  3. SMS Submitted → Failover message sent via SMS.
  4. SMS Delivered → Message successfully delivered.

Example Callbacks

The following callback examples show status updates for an RCS message being rejected and an SMS message being delivered. In both callbacks, you'll see these fields:

  • workflow.workflow_id — Unique ID for the failover workflow.
  • workflow.items_number — Indicates the sequence of the messages sent (e.g. "1" for primary, "2" for the first failover).
  • workflow.items_total — Total number of messages attempted in this workflow.
  • status — Indicates the delivery state. These values will vary depending on the channel, but will be one of submitted, delivered, rejected, undeliverable, or read. Specific information for each channel can be found in the API specification.

RCS Rejected

{
  "messageuuid": "001",
  "to": "447700900000",
  "from": "Vonage",
  "timestamp": "2024-01-01T14:00:02.000Z",
  "status": "rejected",
  "channel": "rcs",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

SMS Delivered

{
  "messageuuid": "002",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:04.000Z",
  "status": "delivered",
  "channel": "sms",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "2",
    "items_total": "2"
  }
}

Use these callbacks to track where and how messages are delivered, and to trigger next actions or logs.

Further Reading