Migrating from Dispatch to Messages Failover

This guide compares the functionality of the Dispatch API with the functionality of the Failover feature in the Messages API, and outlines some things to be aware of when migrating from the Dispatch API to the Messages API Failover functionality.

General Concepts

At a general conceptual level, the Dispatch API and the Failover feature in the Messages API are broadly similar. Both things let you:

Specify an initial message, with fallback message(s) to be sent should the initial message not be delivered.
Fail over between different message types.
Fail over between different messaging channels.

There are, however, some important differences to be aware of. The table below provides a brief overview of some of these differences, which are explained in more detail in the rest of the document.

Dispatch API	Messages API Failover
Fail over logic based on `condition_status` and `expiry_time` properties	Fail over logic based on message being `rejected`
Provides two types of message status webhook: individual messages and final report	Provides one type of message status webhook
-	Supports additional channels, such as RCS, as well as additional message types
Uses Messages v0.1	Implemented in Messages v1
Not supported in Server SDKs	Supported in Server SDKs

Key Differences

The main difference between Dispatch API and Messages API Failover is the logic by which the fail over is triggered.

The Dispatch API defines a workflow array containing an object for each message in a workflow except for the last one. Within that object a condition_status property is set specifying the status of the message to be returned within the specified expiry_time. If the status is not returned within the expiry_time, then the workflow fails over to the next message.
The Failover feature of the Messages API defines the properties for the initial message and then includes an optional failover array containing the message objects for the remaining messages in the workflow. It doesn’t define separate conditions for each message in a workflow; instead, the workflow fails over to the next message if the current message returns a status of rejected.

There are a few other differences between the two APIs to be aware of. These are discussed in the Other Considerations section.

Making a Request

Both APIs require making a HTTP POST request to their respective URLs (https://api.nexmo.com/v0.1/dispatch/ for the Dispatch API and https://api.nexmo.com/v1/messages for the Messages API).

The Dispatch API uses the Messages API in the background (the Dispatch API is essentially an orchestration layer for the Messages API), so the message objects are similar with regards to the properties they contain. However, Dispatch uses Messages v0.1 and the Messages Failover feature is implemented in Messages v1 (see Other Considerations), so the JSON structure of the message objects is different (v1 uses a flatter structure).

Below are examples of making a request with both APIs.

Dispatch API

{
   "template":"failover",
   "workflow": [
		{
			"from": { "type": "mms", "number": "447900000000" },
			"to": { "type": "mms", "number": "447900000001" },
			"message": {
				"content": {
				"type": "img",
				"image": { "url": "https://example.com/image.jpg" }
				}
			},
			"failover":{
				"expiry_time": 600,
				"condition_status": "delivered"
			}
		},
		{
			"from": {"type": "sms", "number": "447900000000"},
			"to": { "type": "sms", "number": "447900000001"},
			"message": {
				"content": {
				"type": "text",
				"text": "This is an SMS sent via the Dispatch API"
				}
			}
		}
   ]
}

The above example demonstrates a Dispatch API workflow that fails over from an MMS image message to an SMS text message. If a delivered status is not received for the MMS image message within 600 seconds, the SMS text message is sent.

Messages API

{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "mms",
	"message_type": "image",
	"image": {
		"url": "https://example.com/image.jpg"
	},
	"failover": [
		{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "sms",
	"message_type": "text",
	"text": "Hello from Vonage!"
		}
	]
}

The above example demonstrates a Messages API workflow that fails over from an MMS image message to an SMS text message. If a rejected status is received for the MMS image message, the SMS text message is sent.

Responses

Both APIs return similar responses for successful requests.

Dispatch API

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

The dispatch_uuid is used for identifying the Dispatch workflow in the context of Message Status webhooks.

Messages API

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

The message_uuid is present for all requests, and is used for identifying the initial message in the context of Message Status webhooks. The workflow_id is only present for requests which include the failover array, and is used for identifying the workflow as a whole.

Message Status Webhooks

Message Status webhooks are triggered by a change in status of an individual message, and are sent to a webhook endpoint defined in the Vonage account settings or Vonage application settings.

As with the message objects themselves, the JSON structure of the webhook payload differs between the APIs. Additionally, the Dispatch API sends two types of Status webhook, whereas the Messages API sends only one type.

Dispatch API

The Dispatch API sends:

Status webhooks are sent in relation to individual messages within the workflow.
A ‘final report’ status webhook is sent if/when the specified condition_status for a message within the workflow is met within the set expiry_time, or if the final message in a workflow is not able to be delivered.

Individual Message Webhooks

These contain a message_uuid which identifies the individual message in relation to the Messages API. They also contain a workflow object with a dispatch_uuid property; the value of this property matches what is received in the response to the initial request, and identifies the overall Dispatch workflow.

{
	"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"to": {
		"type": "sms",
		"number": "447700900001"
	},
	"from": {
		"type": "sms",
		"number": "447700900000"
	},
	"timestamp": "2020-01-01T14:00:00.000Z",
	"status": "rejected",
	"error": {
		"code": 1300,
		"reason": "Not part of the provider network"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"_links": {
		"workflow": {
				"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
		}
	}
}

Final Report Message Webhook

This contains a dispatch_uuid property; the value of this property matches what is received in the response to the initial request, and identifies the overall Dispatch workflow. It also contains a status of either completed if the specified condition_status for a message within the workflow is met within the set expiry_time, or error if the final message in the workflow is not able to be delivered.

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"template": "failover",
	"status": "completed",
	"timestamp": "2020-01-01T14:00:00.000Z",
	"usage": {
		"price": "0.02",
		"currency": "EUR"
	},
	"_links": {
		"messages": [
			{
				"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"channel": "mms",
				"usage": {
						"currency": "EUR",
						"price": "0.0333"
				},
				"status": "submitted"
			}
		]
	}
}

Messages API

The messages API sends a status webhook for any change in status. For messages where the failover property was included, the JSON payload will include a workflow object. This object will contain three properties:

workflow_id: Unique ID for the failover workflow. Matches the value of the workflow_id returned in the response to the initial API request.
items_number: Indicates the specific message within the workflow to which the status relates; e.g. 1 for the initial message, 2 for the first message in the failover array, and so on.
items_total: Total number of messages defined in the workflow.

{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"to": "447700900000",
	"from": "447700900001",
	"timestamp": "2025-02-03T12:14:25Z",
	"status": "delivered",
	"workflow": {
		"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
		"items_number": "1",
		"items_total": "2"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"channel": "sms",
	"destination": {
		"network_code": "12345"
	},
	"sms": {
		"count_total": "2"
	}
}

Other Considerations

As well as the differences already outlined, there are a few other things to bear in mind when migrating from Dispatch API to the Failover functionality of Message API.

Messages API Version

As mentioned elsewhere in this document, the Dispatch API is essentially an orchestration layer on top of the Messages API. It’s important to note though that the Messages API currently has two versions: v0.1 and v1. The Dispatch API uses Messages v0.1 and the Messages Failover functionality is implemented in v1. As well as a difference in the structure of the JSON payload, there are some other differences between the versions worth mentioning.

Messages v1 supports additional channels and message types compared to v0.1. For example v1 supports the RCS channel (a common use-case for failover is from RCS to SMS). Even within channels supported by both, v1 supports some additional message types such as MMS text, file and content message types.
There are a number of other additional features provided in v1 compared to v0.1

Server SDKs

The Messages API (v1) is implemented in the Vonage Server SDKs, whereas the DIspatch API is not. The Messages API implementation in the Server SDKs includes the Messages Failover functionality. There are Server SDKs for Node JS, PHP, Python, Java, Kotlin, .NET, and Ruby. The SDKs let you easily integrate the Messages API into your applications without having to implement your own wrapper for the API endpoint.

Additional Resources

For more information on Dispatch API and Messages API, including the Failover functionality, you can refer to the documentation pages linked below: