The guide below shows how to use the failover functionality of the Workflows API.

1. Configure your Delivery Receipt and Inbound Message endpoint with Nexmo

From Nexmo Dashboard  , go to Settings  .

Set the HTTP method to POST and enter your endpoint in the fields labeled Webhook URL for Inbound Message and Webhook URL for Delivery Receipt:

Screenshot

For testing, you can use requestb.in  to see the data passed to the webhooks.

2. Generate a JWT to Authenticate with Nexmo

As with the Messages API, the Workflows API authenticates using JWT.

In order to create a JWT for you Nexmo API key you will need to create a Nexmo Voice Application. This can be done under the Voice tab  or using the Nexmo CLI  tool.

You will be asked to provide an Event URL and an Answer URL when creating a Voice Application. These are currently only used by the Voice API and are ignored by the Messages and Workflows APIs. Instead the Messages API and Workflows API use the Delivery Receipt and Inbound Message URLs that you set in Settings  .

Once you have created a Voice application you can use the application ID and private key to generate a JWT. There is more information on Voice Application management  and the use of Nexmo libraries  .

If you're using the Nexmo CLI the command is:

$ JWT="$(nexmo jwt:generate /path/to/private.key \application_id=NEXMO_APPLICATION_ID)"
$ echo $JWT

3. Send a message with failover

Sending an message with failover to another channel is done by making one request to the Workflows API endpoint. In this example we will send a Facebook Messenger message that when the failover condition is met (i.e. the message has not been read), the API will proceed to send an SMS.

Key Description
NEXMO_APPLICATION_ID The ID of the application that you created.
FROM_NUMBER The phone number you are sending the message from in E.164  format. For example 447700900000.
SENDER_ID Your sender ID. This value should be the to.id value you received in the inbound messenger event.
RECIPIENT_ID The recipient ID is the Facebook user you are messaging. This value should be the from.id value you received in the inbound messenger event. It is sometimes called the PSID.

Prerequisites

Example

curl -X POST https://api.nexmo.com/beta/workflows \
  -H 'Authorization: Bearer $JWT'\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
    "template":"failover",
    "workflow": [
      {
        "from": { "type": "messenger", "id": "SENDER_ID" },
        "to": { "type": "messenger", "id": "RECIPIENT_ID" },
        "message": {
          "content": {
            "type": "text",
            "text": "This is a Facebook Messenger Message sent from the Workflows 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 Workflows API"
          }
        }
      }
    ]
  }'
http POST 'https://api.nexmo.com/beta/workflows' \
  'Authorization':'Bearer '$JWT\
  template="failover" \
  workflow:='[
    {
      "from": { "type": "messenger", "id": "SENDER_ID" },
      "to": { "type": "messenger", "id": "RECIPIENT_ID" },
      "message": {
        "content": {
          "type": "text",
          "text": "This is a Facebook Messenger message sent from the Workflows API"
        }
      },
      "failover": {
        "condition_status": "read",
        "expiry_time": 600
      },
    },
    {
      "to": { "type": "sms", "number": "TO_NUMBER" },
      "from": { "type": "sms", "number": "FROM_NUMBER" }
      "message": {
        "content": {
          "type": "text",
          "text": "This is an SMS sent from the Workflows API"
        }
      },
    }
  ]'
const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET,
  applicationId: NEXMO_APPLICATION_ID,
  privateKey: NEXMO_APPLICATION_PRIVATE_KEY_PATH
})

nexmo.workflow.create("failover", [
  {
    "from": { "type": "messenger", "id": "SENDER_ID" },
    "to": { "type": "messenger", "id": "RECIPIENT_ID" },
    "message": {
      "content": {
        "type": "text",
        "text": "This is a Facebook Messenger message sent from the Workflows 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 Workflows API"
      }
    }
  },
  (err, data) => { console.log(data.workflow_uuid); }
])