How to send a Failover message

Routee Failover API gives you the ability to create communication flows that will help you reach your audience.

With Failover API you can send a message using multiple digital communication channels like Viber, SMS and Voice.

You will need to use the Failover API:

All your requests should contain headers for authorization and content type:

KEY

VALUE

Authorization

Bearer {access_token}

Content-Type

application/json

An example request is shown below:

curl --request POST \
  --url https://connect.routee.net/failover
  --header 'authorization: Bearer 12dc9ff4-7df4-4786-8e7a-a46d317687f4' \
  --header 'content-type: application/json' \
  --header 'Expect:' \
  --data '{
        "flow":[  
      {  
         "type":"Sms",
         "from":"senderId",
         "to":"+3069xxxxxxxx",
         "ttl":30,
         "message":{  
            "body":"The sms message to be sent",
            "flash":true,
            "label":"string",
            "transcode":true
         },
         "order":1,
         "failoverOnStatuses":[  
            "FAILED",
            "UNDELIVERED"
         ]
      },{
            "type": "Voice",
            "from": "ASenderId",
            "to": {
                "phone": "+306981234567",
                "viber": "",
                "sip": ""
            },
            "dialPlan": {
                "verbs": [
                    {
                        "type": "PLAY",
                        "repeat": 2,
                        "fileURL": "http://www.externalharddrive.com/waves/animal/monkey.wav",
                        "bargeIn": false
                    },
                    {
                        "type": "SAY",
                        "repeat": 3,
                        "bargeIn": false,
                        "message": {
                            "language": "en-US",
                            "gender": "female",
                            "text": "Failover Voice Dialplan"
                        }
                    }
                ]
            },
            "machineDetection": {
                "strategy": "Hangup"
            },
            "order": 2,
            "failoverOnStatuses": [
                "Busy",
                "NoAnswer"
            ]
        },
      {  
         "type":"Viber",
         "senderInfoTrackingId":"0094d198-4dd2-4fb5-b451-d46aca191b27",
         "to":"+3069xxxxxxxx",
         "inboundUrl":"https://inbound.url",
         "ttl":30,
         "expireOnDelivery":false,
         "message":{  
            "text":"string",
            "imageUrl":"https://image.url",
            "action":{  
               "caption":"Go",
               "targetUrl":"https://www.routee.net/"
            }
         },
         "order":2,
         "failoverOnStatuses":[  
            "EXPIRED",
            "FAILED",
            "UNDELIVERED"
         ]
      }
   ],
   "callback":{  
      "strategy":"OnCompletion",
      "url":"https://target.url"
   }

}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}");
Request request = new Request.Builder()
  .url("https://connect.routee.net/failover")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();
var client = new RestClient("https://connect.routee.net/failover");
var request = new RestRequest(Method.POST);
request.AddHeader("Cache-Control", "no-cache");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/failover",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}",
  CURLOPT_HTTPHEADER => array(
    "Cache-Control: no-cache",
    "Content-Type: application/json",
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPConnection("connect,routee,net")

payload = "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}"

headers = {
    'Content-Type': "application/json",
    'Cache-Control': "no-cache",
    }

conn.request("POST", "failover", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://connect.routee.net/failover")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Cache-Control"] = 'no-cache'
request.body = "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}"

response = http.request(request)
puts response.read_body
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://connect.routee.net/failover",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache"
  },
  "processData": false,
  "data": "{\n  \t\t\"flow\":[  \n      {  \n         \"type\":\"Sms\",\n         \"from\":\"senderId\",\n         \"to\":\"+3069XXXXXXXX\",\n         \"ttl\":30,\n         \"message\":{  \n            \"body\":\"The sms message to be sent\",\n            \"flash\":true,\n            \"label\":\"string\",\n            \"transcode\":true\n         },\n         \"order\":1,\n         \"failoverOnStatuses\":[  \n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      },\n      {  \n         \"type\":\"Viber\",\n         \"senderInfoTrackingId\":\"0094d198-4dd2-4fb5-b451-d46aca191b27\",\n         \"to\":\"+3069xxxxxxxx\",\n         \"inboundUrl\":\"https://inbound.url\",\n         \"ttl\":30,\n         \"message\":{  \n            \"text\":\"string\",\n            \"imageUrl\":\"https://image.url\",\n            \"action\":{  \n               \"caption\":\"Go\",\n               \"targetUrl\":\"https://www.routee.net/\"\n            }\n         },\n         \"order\":2,\n         \"failoverOnStatuses\":[  \n            \"EXPIRED\",\n            \"FAILED\",\n            \"UNDELIVERED\"\n         ]\n      }\n   ],\n   \"callback\":{  \n      \"strategy\":\"OnCompletion\",\n      \"url\":\"https://target.url\"\n   }\n\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

The "senderInfoTrackingId" is unique and can be retrieved from Routee Platform. The Applications page contains all the information you need.

Your application at callback.url will receive a callback notification with information about your message's status.

You will receive a POST HTTP request with the following request body:

{
  "trackingId": "1e5400aa-9a4a-4c58-9040-6dbdc8a324c1",
  "messages": [
    {
      "messageId": "bf4ac2b9-4aee-41ef-8bb6-defa0402f8ed",
      "from": "senderId",
      "to": "+306912345678",
      "body": "The sms message to be sent",
      "country": "GR",
      "status": {
        "name": "Undelivered",
        "reason": {
          "detailedStatus": "Opted-out",
          "description": "Message cannot be sent to the destination number because the customer has replied with STOP"
        },
        "updatedDate": "2021-06-09T13:21:02Z"
      },
      "part": 1,
      "parts": 1,
      "latency": 0,
      "label": "string",
      "order": 1,
      "ttl": 1,
      "failoverOnStatuses": [
        "Undelivered",
        "Failed"
      ],
      "createdAt": "2021-06-09T13:21:02.251Z",
      "type": "Sms"
    },
    {
      "trackingId": "f108f844-f472-49f4-9e52-f20dffe1d205",
      "from": "senderId",
      "to": "+381234567890",
      "body": {
        "text": "The sms message to be sent",
        "action": {
          "caption": "1",
          "targetUrl": "https://www.routee.net"
        }
      },
      "status": {
        "name": "EXPIRED",
        "reason": {
          "detailedStatus": "Expired",
          "description": "Message expired."
        },
        "updatedDate": "2021-06-09T13:21:34.772Z"
      },
      "country": "RS",
      "price": 0,
      "inboundUrl": "https://webhook.site/ea465686-86da-4b67-b317-60a7101f80fb",
      "label": "",
      "order": 2,
      "ttl": 0.5,
      "failoverOnStatuses": [
        "EXPIRED",
        "UNDELIVERED",
        "FAILED"
      ],
      "createdAt": "2021-06-09T13:21:02.745Z",
      "expireOnDelivery": false,
      "type": "Viber"
    },
    {
      "messageId": "506cef16-d7e4-4a60-9c71-2c42e1a6739b",
      "conversationTrackingId": "6cc3485a-2340-430d-b073-e50fc94b0269",
      "from": "senderId",
      "to": "+306912345678",
      "country": "GR",
      "status": {
        "name": "Completed",
        "reason": "",
        "description": "",
        "updatedDate": "2021-06-09T13:22:13.038Z"
      },
      "duration": 4,
      "price": 0.0039466668,
      "chargeInterval": 1,
      "order": 3,
      "failoverOnStatuses": [
        "Busy",
        "Terminated",
        "Failed",
        "Unsent",
        "NoAnswer"
      ],
      "createdAt": "2021-06-09T13:21:35.052Z",
      "type": "Voice"
    }
  ],
  "terminationChannel": "Voice",
  "status": "Succeeded",
  "totalPrice": 0.0039466668,
  "originatingService": "failover",
  "applicationId": "5bac9a79de9f802a0512e785",
  "createdAt": "2021-06-09T13:21:02.209Z",
  "updatedAt": "2021-06-09T13:21:44.726Z"
}

Some features that are interesting in the Failover Service is that you can create the communication flow selecting the different digital communication channels and also the exact statuses for each channel that will lead to changing to another channel.

For example you can create a flow using Viber and SMS. The Viber channel comes first in the flow ("order":1) and the flow will continue with the next channel, SMS, if the Viber status is "UNDELIVERED".

Failover also gives you the ability to select if the Failover will get activated "OnCompletion" meaning when a final status arrives or "OnStep" meaning on every status change. This gives you the flexibility to not have to wait for the Viber ttl to expire but send the Failover message via SMS instantly if the "OnStep" strategy is selected. Below the example code:

curl --request POST \
  --url https://connect.routee.net/failover
  --header 'authorization: Bearer 12dc9ff4-7df4-4786-8e7a-a46d317687f4' \
  --header 'content-type: application/json' \
  --header 'Expect:' \
  --data '{
        "flow":[  
      {  
         "type":"Viber",
         "senderInfoTrackingId":"0094d198-4dd2-4fb5-b451-d46aca191b27",
         "to":"+3069xxxxxxxx",
         "inboundUrl":"https://inbound.url",
         "ttl":30,
         "expireOnDelivery":false,
         "message":{  
            "text":"string",
            "imageUrl":"https://image.url",
            "action":{  
               "caption":"Go",
               "targetUrl":"https://www.routee.net/"
            }
         },
         "order":1,
         "failoverOnStatuses":[  
            "EXPIRED",
            "FAILED",
            "UNDELIVERED"
         ]
      },
      {  
         "type":"Sms",
         "from":"senderId",
         "to":"+3069xxxxxxxx",
         "ttl":30,
         "message":{  
            "body":"The sms message to be sent",
            "flash":true,
            "label":"string",
            "transcode":true
         },
         "order":2,
         "failoverOnStatuses":[  
            "FAILED",
            "UNDELIVERED"
         ]
      }
   ],
   "callback":{  
      "strategy":"OnStep",
      "url":"https://target.url"
   }

}'

📘

Failover API available

Routee provides a single API for an easy Failover implementation across multiple channels.
Read more details about the Failover API here: https://docs.routee.net/docs/failover
Read the Failover API reference here: https://docs.routee.net/reference/send-a-failover-message