Introducing Message Failover in Vonage Messages API

Message failover is now available in the Vonage Messages API. Before we dive into what failover is and how to use it, let’s do a brief overview of the Messages API for anyone who might not be familiar with it.

Messages API Overview

The Messages API is a multi-channel messaging API that enables businesses to send and receive various message types across multiple messaging channels, including SMS, MMS, RCS, WhatsApp, and more.

The exact JSON structure of the API request payload varies depending on the channel and/or message type, but all messages follow the same basic principles.  The JSON for all messages would have properties for to, from, channel, and message_type, as well as a property for the message itself, which would vary depending on the message type. There are also additional optional properties, some of which relate to specific features supported by a certain channel or message type.

For example, this would be the JSON structure for sending a basic text message via the sms channel:

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!"
}

A basic image message sent via the rcs channel would use JSON structured something like this:

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    }
}

The response to the API request will contain a response body with a message_uuid property, which uniquely identifies the message object on Vonage’s servers. This UUID can then be used for tracking the status of the message.

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

Message Status

Once the initial API request has been made, the message object will progress through various statuses, such as submitted and delivered, as the Messages API attempts to deliver it to the specified recipient via the downstream network of the required channel.

A change in status will trigger a HTTP request to be sent to the Status webhook endpoint defined in your Vonage Application settings. The request body will have a JSON payload structured something like this (though there may be additional properties depending on the channel and status):

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered"
}

Specific statuses may vary slightly depending on the channel. For example, channels such as RCS and WhatsApp have a read status indicating that a delivered message has now been read by the recipient, whereas SMS and MMS channels do not have the capability for providing read statuses.

One message status that all channels have in common is the rejected status. Depending on the channel and/or message type, there could be various reasons why a message has been rejected. In all cases though, a rejected status means that the message will not be delivered to the recipient.

What Message failover is

Before failover was implemented in the Vonage Messages API, if you wanted to build some resilience into your messaging application in order to deal with situations where messages were rejected, you would have needed to implement the business logic for this yourself. For example, you could orchestrate a system to track the status of an individual message request using the Message Status webhook messages using the message_uuid value returned in the initial HTTP, and if a rejected status was received for a message object make a request for a fall-back message to be sent.

With the failover feature, this type of logic can be incorporated into the initial message request itself. Let’s find out how!

Using Failover in the Messages API

To use failover in the Messages API you need to include an additional failover property in the JSON payload that defines the message. The value of this property is an array that contains one or more message objects.

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     // message objects
   ]
}

If the initial message is rejected, then the Messages API will automatically send the first message object in the failover array. If that message is also rejected then the second object (if one is defined) will be sent, and so on.

When including the failover property in the API request, a message_uuid is received in the HTTP response as usual, but an additional property, workflow_id is also included:

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

When receiving Message Status webhook requests for message objects that were sent with a failover property, the JSON payload will include a workflow object with the workflow_id property, the value of which will match the workflow_id received in the response to the initial API request. In this context, a ‘workflow’ represents the series of messages – the initial message and the defined failover message(s).

In addition, the workflow object will contain an items_number property and an items_total property. The items_number indicates which ‘item’ or message within the overall workflow this Message Status request relates to. An items_number of 1 indicates the initial message, and items_number of 2 indicates the first message object in the failover array, and so on. The items_total property indicates the total number of ‘items’ or messages in the overall workflow; for example, an items_total of 3 would indicate one initial message with two messages defined in the failover array.

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   }
}

The Messages API will send Message Status requests as necessary for each message in a workflow. So, for example, you could receive a status of rejected for items_number 1, and then a status of delivered (with the same message_uuid and workflow_id) for items_number 2. If, on the other hand,  items_number 1 was delivered then the workflow would be complete and any subsequent messages in the workflow would not trigger Message Status requests.

When to Use Failover

Now that we’ve covered what failover is and how to use it, let’s look at a couple of ways in which it can be used.

Failover Across Channels

You can leverage the multi-channel capability of the Vonage Messages API by attempting to deliver a message to one channel, and if the initial message is rejected, failing over to another channel.

A common use case would be failing over from RCS to SMS. Although RCS is widely supported now (RCS messaging is supported on iOS since v18), it’s still not as widespread in terms of device support and network coverage as SMS. Additionally, some devices require you to enable RCS messaging on the device (i.e. it isn’t enabled by default). Sending a message to a device that doesn’t support RCS would result in that message being rejected. In this situation, you could instead fail over to an SMS message.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Hello from Vonage!"
     }
   ]
}

Multiple Failover

The general idea is similar to the previous example, but with more channels used to provide an appropriate fallback based on the message type. For example, you might want to send a Product message with an image via RCS which fails over to an MMS image if the recipient’s device doesn’t support RCS, and then fails over to SMS if the recipient’s network doesn’t support MMS.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    },
   "failover": [
     {
      "to": "447700900001",
      "from": "447700900000",
      "channel": "mms",
      "message_type": "image",
      "image": {
         "url": "https://example.com/image.jpg"
      }
    },
    {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Check out this image https://example.com/image.jpg"
     }
   ]
}

Conclusion and Next Steps

In this post, we’ve explored failover functionality in the Vonage Messages API. We’ve looked at what failover is, how to use it, and some situations where it might be useful.

If you want to explore failover further you can check out the guide in our developer documentation, code snippet examples demonstrating the use of failover in our Server SDKs, and the full Messages API specification.

Are you building something awesome with the Vonage Messages API, planning to use the failover functionality, or even just have questions about the feature or the API in general? Let us know over at our Vonage Community Slack workspace!