Using failover

This guide shows you how to use the failover functionality of the Workflows API.

The example Workflow given here will attempt to send a Facebook message using the Messages API, and if this fails it then attempts to send an SMS message to the user using the Messages API.

1. Configure your Webhook URLs

If you intend to receive inbound messages you will need to configure an Inbound Message Webhook URL.

To receive updates about the status of a message, such as "delivered" or "read", you need to configure a Delivery Receipt Webhook URL.

If you don't have a webhook server set up, you can use a service like Ngrok  for testing purposes. If you've not used Ngrok before you can find out more in our Ngrok tutorial  .

TIP: If the Webhook URLs for messages in your Nexmo Account are already in production use and you would like a second one for using the Messages API, please email support@nexmo.com and ask for a sub API Key.

From Nexmo Dashboard  go to Settings  .

Enter your Webhook URLs in the fields labeled Webhook URL for Inbound Message and Webhook URL for Delivery Receipt:

Screenshot

NOTE: You need to explicitly set the HTTP Method to POST, as the default is GET.

2. Create a Nexmo Application

In order to create a JWT to authenticate your API requests, you will need to first create a Nexmo Voice Application. This can be done under the Voice tab in the Dashboard  or using the Nexmo CLI  tool if you have installed it  .

When creating a Nexmo Voice Application, you will be asked to provide an Event URL and an Answer URL. These are currently only used by the Voice API and are ignored by the Messages and Workflows APIs, so in this case you can just set them to the suggested values of http://example.com/event and http://example.com/answer respectively.

When you are creating the Nexmo Voice Application in the Nexmo Dashboard  you can click the link Generate public/private key pair - this will create a public/private key pair and the private key will be downloaded by your browser.

Make a note of the Nexmo Application ID for the created application.

3. Generate a JWT

Once you have created a Voice application you can use the Nexmo Application ID and the downloaded private key file, private.key, to generate a JWT.

TIP: If you are using the client library for Node (or other languages when supported), the dynamic creation of JWTs is done for you.

If you're using the Nexmo CLI the command to create the JWT is:

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

This JWT will be valid for fifteen minutes. After that, you will need to generate a new one.

TIP: In production systems, it is advisable to generate a JWT dynamically for each request.

4. Send a message with failover

Sending an message with failover to another channel is achieved by making a single request to the Workflows API endpoint.

In this example you will implement the following workflow:

  1. Send a Facebook Messenger message to the user using the Messages API.
  2. If the failover condition is met proceed to the next step. In this example the failover condition is the message not being read.
  3. Send an SMS to the user using the Messages API.
Key Description
FROM_NUMBER The phone number you are sending the message from. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.
SENDER_ID Your Page ID. The SENDER_ID is the same as the to.id value you received in the inbound messenger event on your Inbound Message Webhook URL.
RECIPIENT_ID The PSID of the user you want to reply to. The 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.

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); }
])