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:

#{alt_text}

Contents

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:

  • cURL

    • Write the code

    Add the following to send-message-with-failover-basic-auth.sh:

    Copy to Clipboard 
    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"
          }
        }
      }
    ]
  }'

    View full source

    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.

    Code Snippets

    Use Cases

    Reference