Overview

During an emergency, two things are important. The first is to notify the right stakeholders immediately and second is to act fast towards a solution. Imagine a scenario where i) a patient enters a hospital with a critical condition which needs to be passed immediately to a set of folks (Doctor, ET, Labs etc) to save the life of a patient. The designated stakeholders should be aware before about the specifics of the condition. This is where Exotel SOS calling comes into play.

About SOS calling

SOS calling using Exotel cloud telephony is the most cost effective and simplest way to use Exotel for emergencies. This solution will be further extended to IOT systems, fire alarms, burglar alarms etc to alert the authorities. For example, a car or bike fitted with an IOT device capable of detecting a collision or fall can set off an emergency call to a set of predefined phone numbers. Those numbers receive a call on their phones with a dynamic message played by a bot. Or if you are into a business of providing Cloud solutions and you constantly want to monitor your uptimes, this solution is great to notify the engineers if there is a code break or a server downtime.

Going back to the scenario of a hospital, a front desk person receiving the patient calls into a Virtual number and records the condition of the patient. It can have details like Blood pressure, Pulse rate, SPO2 levels of the patient etc. Once the message is recorded, Exotel triggers a call to a set of predefined numbers and plays the message recorded earlier. In case you want to add more channels of communication, integrate Exotel SMS API as well to send an SMS. Well if you are tech savvy and have some understanding of Whatsapp Business API, you can trigger a whats app notification as well. Isn’t that a great way to use technology to save people’s lives ? Well yes, now look at how you can set this up

Pre-requisites

An active Exotel account.
The authentication Key and Token.
Integration to be completed by the customer development team using API Documentation.

Flow 1

Flow 2

How it works ?

Let’s first build and understand the individual components and then connect the dots:

Step 1 Call Flow Creation

Here we will be creating two call flows in Exotel dashboard. The first one is Incoming call flow i.e “Voicemail Call Flow” and the second one is Outbound call flow i.e “Dynamic Greeting Flow” to play out the pre-recorded message.

1.1 Incoming Voicemail Flow

Applets required: IVR Menu, Voicemail and Passthru
A GET webhook to be developed by your tech team for storing Recording and Emergency type.

1.2 Outbound Dynamic Greeting Flow

Applets required: Greeting, Hangup
A webhook to be developed by your tech team which returns the previously stored audio file in the Greeting Applet.

Step 2: Configuring Passthru and Dynamic Greeting

2.1 Passthru configuration

A Passthru applet allows communication between Exotel database and your database to send and receive data through a web service. Here Exotel makes a GET request to your webservice and sends data in the form of a query string.

GET

https://yourGETendpoint.com/storelogs?CallSid=fd7a090139691d5ed3exxg&CallFrom=0932419xx&CallTo=0224xx&Direction=incoming&Created=Fri, 16 Jul 2021 15:41:28&DialCallDuration=0&RecordingUrl=https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/xx_0.mp3&StartTime=2021-07-16 15:41:28&EndTime=1970-01-01 05:30:00&CallType=voicemail&DialWhomNumber=&flow_id=156027&tenant_id=61694&From=0932xxx&To=022489xx&RecordingAvailableBy=Fri, 16 Jul 2021 15:47:25&CurrentTime=2021-07-16 15:42:25&EmergencyType=Heart

You can read more about the actual payload sent by Exotel in the Resource section.

Before hosting an endpoint in your server, you can also create a dummy endpoint through freemium websites likeYou can read more about the actual payload sent by Exotel in the Resource section.

For this usecase, the most important parameters are RecordingUrl and EmergencyType. EmergencyType is the custom attribute created here for this usecase whereas RecordingUrl exists in the Exotel system.

2.2 Dynamic Greeting configuration

Read more about Dynamic Greeting here.
Exotel will make a GET request with a parameter “CustomField” which contains the url of the audio file to be played.
Custom Field acts as an identifier to understand which audio file should be returned. Custom field is explained in detail in another section of the call API.
The response to this request should be the audio file url in plain text format which Exotel will play out to predefined phone numbers.

Step 3: Integrating Connecting to a Flow API

The API will be called as soon as you receive data from Passthru URL configured in step 2.1. This API allows you to make automated voice calls to the set of phone numbers defined. Each API hit makes a call to one phone number, hence if you are calling 20 phone numbers, you will call the API 20 times, each time passing a unique phone number to be called.

Check the API documentation

Sample request
cURL

curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect \
-d "From=XXXXX30240" \
-d "CallerId=0XXXXXX4890" \
-d "Url=http://my.exotel.com/{your_sid}/exoml/start_voice/926"
-d "CustomField=https://s3_recordingurl.com/exotel.mp3"

Sample Response
JSON

 "Call": {
    "Sid": "80bfbec2d78bbbf10fb851f4fa165211",
    "ParentCallSid": null,
    "DateCreated": "2017-03-03 12:30:24",
    "DateUpdated": "2017-03-03 12:30:27",
    "AccountSid": "Exotel",
    "To": "0XXXXX40682",
    "From": "0XXXXX30240",
    "PhoneNumberSid": "0XXXXXX4890",
    "Status": "in-progress",
    "StartTime": "2017-03-03 12:30:27",
    "EndTime": null,
    "Duration": null,
    "Price": null,
    "Direction": "outbound-api",
    "AnsweredBy": null,
    "ForwardedFrom": null,
    "CallerName": null,
    "Uri": "/v1/Accounts/Exotel/Calls.json/80bfbec2d78bbbf10fb851f4fa165211",
    "RecordingUrl": null
  }
}

Stitching the pieces together

A receptionist/ front desk agent calls the Exotel Virtual number allocated.
For this case let’s have an IVR menu with Heart, Brain and Lungs and other emergencies.
Once an option is pressed on IVR, the system will prompt the user to record the message and press the hash key when finished.
Use a Passthru applet after the Voicemail applet to store the Emergency type and Voicemail recorded in your database.
Once you store parameters “EmergencyType” & “RecordingUrl”, use “Connecting to a flow API ” and make the announcement.

How to implement this for other scenarios ?

The above configuration can be used for other situations as well for example:

Server downtime alerts
Burglar alarm
Iot devices fitted for detecting a crash or an accident.

In all these cases, we can ignore step 1.1 and 2.1 as there is no incoming call flow involved here. The configuration begins with Step 3 where “Connecting to a flow API” will be triggered and it will hit an Outbound flow elaborated in step 2.2.

Expanding to other communication channels:

You might be curious about how to add other communication channels apart from calls ? Well, you can certainly add SMS and Whatsapp as well.

For SMS, Exotel itself has its own infrastructure to provide you with SMS functionality. You can make use of Exotel SMS API and send Emergency text along with audio URL (hospital alerts) or a dynamic text in case of other scenarios.

For whatsapp, you can integrate APIs of Whats app resellers like GupShup, Infobip, ValueFirst etc. Please get in touch with your Whats app service provider to get access to their APIs. For the purpose of understanding, we will make use of the GupShup API.

Step 4: Integrating SMS API

In step 3, we invoked a call API to alert the stakeholders. Simultaneously, if you want to send an SMS as well, you can call the SMS API.

Sample Request
cURL

curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Sms/send \
-d "From=0XXXXXX4890" \
-d "To=XXXXX30240" \
-d "Body=Hello World!"\
-d "Priority=High" \
-d "DltEntityId=<your_id>" \
-d "DltTemplateId=<template_id>" \
-d "SmsType=<transactional>"

Sample Response
JSON

{
  "SMSMessage": {
    "Sid": "0f477d60517e6e6a0f6d9a7e9af8630e",
    "AccountSid": "Exotel",
    "From": "0XXXXXX4890/WEBDEV",
    "To": "0XXXXX30240",
    "DateCreated": "2017-03-03 14:14:20",
    "DateUpdated": "2017-03-03 14:14:20",
    "DateSent": null,
    "Body": "Hello World!",
    "Direction": "outbound-api",
    "Uri": "/v1/Accounts/Exotel/Sms/Messages.json/0f477d60517e6e6a0f6d9a7e9af8630e",
    "ApiVersion": null,
    "Price": null,
    "Status": "queued"
    "DetailedStatusCode": "21010"
    "DetailedStatus": "PENDING_TO_OPERATOR"   
  }
}

In the “Body” parameter, you can pass the nature of Emergency and audio URL received from passthru.

Step 5: Integrating WhatsApp API

Exotel does not provide Whats app service hence you can integrate APIs of Whats app resellers like GupShup, Infobip, ValueFirst etc. Please get in touch with your Whats app service provider to get access to their APIs. For the purpose of understanding, we will make use of the GupShup API.

Sample Request:
cURL

curl --location --request GET 'https://media.smsgupshup.com/GatewayAPI/rest?method=SendMessage&format=json&userid=<gupshup_user_id>&password=<gupshup_account_pwd>&send_to=<phone_number>&v=1.1&auth_scheme=plain&msg_type=HSM&msg=There is an emergency for Heart Patient. Here are the condition details:<recording_url>&isTemplate=true'

Sample Response:
JSON

{
    "response": {
        "id": "4346061160655278347-94984840088419718",
        "phone": "918699649964",
        "details": "",
        "status": "success"
    }
}

Exotel for Emergencies - Here is a quick blog on how Hiranandani Hospital from Mumbai implemented a low cost solution for handling Cardiac and Brain related emergencies.

To have a quick feel of the solution, you can call this number 022-489-66395 and record a message. In this scenario, we will make a call back to your number only with the message recorded by you.

Cost effective, no infrastructure needed!
Easy to scale up.
Plug and play REST API's

SOS calling is used by Hospitals, IT and Cloud based solutions providers. Exotel internally used this solution to alert respective Engineers in case of any errors coming up in the system.

Resources

SOS calling Pricing

There are three SKUs under this solution:

Software Rentals: This is monthly fixed charge for availing the Exotels services
Call Charges: Normal call charges, charged at pulse rate (where pulse can be 30s, 60s, or any other agreed upon value)
Virtual number rental: Based on the plan selected, Virtual number rental will be applicable. You can read more about pricing plans here.
SMS Charges: SMS charges will be applicable in case you are planning to incorporate this.