Dispatch API Overview
The Dispatch API enables the developer to send messages to users using a multiple channel strategy.
An example workflow might specify a message to be sent a message via Facebook Messenger, and if that message is not read then the user can be sent a message via Viber. If that message is also not read, a user could then be sent a message via SMS.
The Dispatch API provides the mechanism by which to order messages and specify their success conditions. The Dispatch API uses the Messages API to actually send the messages.
The following diagram illustrates the relationship between the Dispatch API and the Messages API:
Contents
- Beta
- Supported features
- External Accounts API
- Getting started
- Concepts
- Building Blocks
- Tutorials
- Reference
Beta
This API is currently in Beta.
In this release Nexmo provides a failover template. The failover template instructs the Messages API to send a message to the specified channel. If that message fails immediately or if the condition_status
is not reached within the specified time period the next message is sent.
Nexmo always welcomes your feedback. Your suggestions help us improve the product. If you do need help, please email support@nexmo.com and include Workflow API in the subject line. Please note that during the Beta period, support times are limited to Monday to Friday.
Supported features
In this release you can:
- Send SMS, Facebook Messenger, WhatsApp, and Viber Service Messages with Dispatch built on-top of the Messages API.
- Failover to the next message if the condition status is not met within the time period or if the message immediately fails.
The condition status is the status that the message returns. With Facebook Messenger and Viber Service Messages, you can use delivered
and read
statuses as the condition status. With SMS you can only use delivered
.
External Accounts API
The External Accounts API is used to manage your accounts for Viber Service Messages, Facebook Messenger and WhatsApp when using those channels with the Messages and Dispatch APIs.
Getting started
In this example you will need to replace the following variables with actual values using any convenient method:
Key | Description |
---|---|
NEXMO_API_KEY |
Nexmo API key which can be obtained from your Nexmo Dashboard. |
NEXMO_API_SECRET |
Nexmo API secret which can be obtained from your Nexmo Dashboard. |
FB_SENDER_ID |
Your Page ID. The FB_SENDER_ID is the same as the to.id value you received in the inbound messenger event on your Inbound Message Webhook URL. |
FB_RECIPIENT_ID |
The PSID of the user you want to reply to. The FB_RECIPIENT_ID is the PSID of the Facebook User you are messaging. This value is the from.id value you received in the inbound messenger event on your Inbound Message Webhook URL. |
FROM_NUMBER |
A phone number you own or some text to identify the sender. |
TO_NUMBER |
The number of the phone to which the message will be sent. |
NOTE: Don't use a leading +
or 00
when entering a phone number, start with the country code, for example 447700900000.
The following code shows how to create a workflow that attempts to send a message via Facebook messenger and if not read within the time limit a message will be sent via SMS:
Write the code
Add the following to send-message-with-failover-basic-auth.sh
:
curl -X POST https://api.nexmo.com/v0.1/dispatch \
-u "$NEXMO_API_KEY:$NEXMO_API_SECRET" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d $'{
"template":"failover",
"workflow": [
{
"from": { "type": "messenger", "id": '$FB_SENDER_ID' },
"to": { "type": "messenger", "id": '$FB_RECIPIENT_ID' },
"message": {
"content": {
"type": "text",
"text": "This is a Facebook Messenger Message sent from the Dispatch API"
}
},
"failover":{
"expiry_time": 600,
"condition_status": "read"
}
},
{
"from": {"type": "sms", "number": '$FROM_NUMBER'},
"to": { "type": "sms", "number": '$TO_NUMBER'},
"message": {
"content": {
"type": "text",
"text": "This is an SMS sent from the Dispatch API"
}
}
}
]
}'
Run your code
Save this file to your machine and run it:
bash send-message-with-failover-basic-auth.sh
Concepts
- What is a Dispatch workflow?: Dispatch workflows help you to build a robust messaging plan that incorporates failover to a secondary channel.
Building Blocks
- Before you begin
- Install Nexmo CLI
- Client library
- How to create a Nexmo Messages and Dispatch Application
- Send a Facebook message with failover
- Send a WhatsApp message with failover
- Send a Viber message with failover
- Send an MMS with failover