The Nexmo Messages & Dispatch APIs

First Look at the Nexmo Messages and Dispatch APIs

Published October 10, 2018 by Martyn Davies

Today we moved the Nexmo Messages API and Dispatch API out of developer preview and officially into Beta.

That’s great for us but what does it mean for you? Well, in short, we’re now able to offer you the ability to send messages via Facebook Messenger, WhatsApp, Viber, SMS and MMS using just one API.

Better still, we’ve built in the ability to create fallbacks, so if your message isn’t read on one channel then you can send a backup to another one, or switch to SMS/MMS ensuring that the information you need to convey always gets read.

Let’s take a deeper look into how you can work with these two new APIs.

Messages and Dispatch Architecture

This powerful combination of APIs can be used both independently or in unison depending on what you are trying to achieve.

There are two APIs at play here. The Messages API which handles the sending of any messages to the desired service, and the Dispatch API which is used to build failover templates of messages based on delivery events, such as read receipts.

Messages API and Dispatch API Overview

Sending a Message with the Messages API

Currently, there are two ways to use the Messages API. Either by making requests directly to the API endpoints, or by using the Beta release of our Node JS client library.

For the following examples, we’ll be using NodeJS. Let’s start by taking a look at the code needed to send a message via Facebook Messenger.

As you can see, the API requires a series of objects to be passed to it in order to know what to do. Pay particular attention to the first two:

This is where the platform you want to send on is specified, along with your ID (in Facebook’s case this would be the ID given to your business profile page), and the ID of the recipient.

We’ve standardised this format throughout the API. Would you like to take a guess at how you would send a message via WhatsApp instead of Facebook Messenger?

I’ll go ahead and believe that you guessed correctly. The only change needed to shift sending to a completely different messaging service is to the first two objects, other than that the code is exactly the same.

We have several more in-depth tutorials on sending messages with the Messages API ready for you to check out:

It is also worth noting that if you just wanted to send regular SMS messages via the Messages API, you can do so, as it forms an integral part of the service that the Dispatch API performs.

We’ll take a look at Dispatch next, but check out the Sending SMS Messages with the Messages API tutorial if that’s something you’re doing now and want to see how it fits into this new way of working.

Handling Message Failover with the Dispatch API

Ensuring your messages and replies get to your customers is crucial to providing a top-notch experience. As developers, being able to seamlessly ‘fail over’ from one preferential messaging service to a backup, such as SMS, means that you can keep the conversation flowing.

Herein lies the Dispatch API’s reason for being. Let’s take a look at what it takes to use it.

The code below is an example of a ‘failover template’ and it’s being used to send the important contents of the myMessage variable.

A failover template is made up of three required parts:

  1. The initial message you want to send (on whichever messaging platform you want to send it, in this case it is a Viber Service Message).
  2. A condition_status to wait for. The code above waits 600 seconds (10 minutes) for a delivered status to be returned. If this doesn’t happen, the failover will kick in.
  3. The second object in the array is the instruction of what to do if the first message ‘fails’. In this case, the myMessage content is sent via SMS to the user.

You can find further details the documentation for Dispatch workflows including which condition_status you can expect from the different platforms.

For a more detailed look at building with the Dispatch API, see our Sending a Facebook Message with failover tutorial.

Your Feedback Is Important

Nexmo always welcomes your feedback. Your suggestions help us improve the product and we’d love to know what you are building with these APIs.

If you do need help, please email and include Messages & Dispatch APIs in the subject line. Please note that during the Beta period, support times are limited to Monday to Friday.

You can also find the Nexmo Developer Relations team and offer up your feedback in the Nexmo Community Slack channel.

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at