Listen Whisper Barge (LWB) API  (Beta)

This document outlines APIs for performing LWB  , to help supervisors perform monitor action on an ongoing call. Inorder to perform the action , this documents describes the below two endpoints which a developer shall use to perform the required action from a supervisor 

  1. Get the active legs of the ongoing call :- Typically an ongoing call shall have two legs , 1 from the customer and 1 from the agent. This API shall return the leg details in order for the developer to identify which is the agent leg to perform the monitor action

  2. Create the monitor leg :- Once the leg is identified , one need to create another leg on the call to perform the required action ( Listen / Whisper / Barge )

 

NOTE :- In Order to use these APIs , one needs to provide the callSID of the ongoing call. This is a dependency for the  API


NOTE :- To enable this API in your account , please reachout to hello@exotel.com 

 

Get the active legs of the ongoing call 

 

An HTTP GET request to  has to be made

https://<your_api_key>:<your_api_token>@<subdomain>/v1/Accounts/<your_sid>/Calls//<callSid>/ActiveLegs

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.

  • Replace <your_sid> with your “Account sid”

  • Replace <subdomain> with the region of your account

    • <subdomain> of Singapore cluster is api.exotel.com

    • <subdomain> of Mumbai cluster is api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

 

 

Sample request :-

curl https://<your_api_key>:<your_api_token>

@api.in.exotel.com/v1/Accounts/<your_sid>/Calls/<CallSid>/ActiveLegs.json

 

HTTP Response:

On success, 

  • the HTTP response status code will be 200

  • the HTTP body will contain an XML similar to the one below ,an array of legs

 

 

{

"Legs":[

{

"Sid":"XXXXXXXXXX",

"CallSid":"XXXXXXXX",

"AccountSid":"XXXXXX",

"EndUserNumber":"xxxx",

"Status":"in-progress",

"Origin":"outbound",

"LastAction":"",

"DateCreated":"2020-12-22 17:31:06",

"DateUpdated":"2020-12-22 17:31:12",

"Uri":"/v1/Accounts/XXXXX/Calls/XXXXXXX/ActiveLegs"

},

{

"Sid":"XXXXX",

"CallSid":"XXXXX",

"AccountSid":"XXXXX",

"EndUserNumber":"xxxx",

"Status":"in-progress",

"Origin":"outbound-dial",

"LastAction":"",

"DateCreated":"2020-12-22 17:31:13",

"DateUpdated":"2020-12-22 17:31:13",

"Uri":"/v1/Accounts/XXXXX/Calls/XXXXX/ActiveLegs"

}

 

Here the Sid if the Leg identifier to be used in creating the monitor action on a leg

 

On Failure, 

<?xml version="1.0" encoding="UTF-8"?>

<TwilioResponse>

<RestException>

<Code>404</Code>

<Message>Given callSID is not in-progress</Message>

</RestException>

</TwilioResponse>sh-3.2# 

 

Create the monitor leg 

This is the supervisor leg which will get created on successful execution of the below API. On 200 OK a call attempt shall be made from Exotel platform to supervisor and on pick up of the call the supervisor shall join the ongoing call in "Listen" "Whisper" or a "Barge" mode 


An HTTP POST request to https://<your_api_key>:<your_api_token>@<subdomain>/v1/Accounts/<your_sid>/Calls/<CallSid>/Legs 

 

The following are the POST parameters:

Field

Mandatory/ Optional

DataType

Values

Action

Mandatory

string

“listen”

“whisper”

“barge”

PhoneNumber

Mandatory

string

New leg will be created for this phone number.

If mobile number, prefix the 10 digits with a 0; Ex:✆✆ 09052161119.

If landline number, prefix it with STD code; Ex: 08030752400

TargetLegSid

Optional

string

Logical Leg ID of the leg on which the action is to be performed

Mandatory if Action = whisper 

StatusCallback

Optional

string

When the call completes, an HTTP POST will be made to the URL mentioned below with the parameters

StausCallbackEvents

Optional

Array

Array of events for which StatusCallback has to be sent. Currently only terminal is supported

CustomField

Optional

string

Application specific value which will passed in the statuscallback

StatusCallbackContentType

Optional

string

Allowed values
multipart/form-data (default)

application/json

 

HTTP Response:

On success, 

  • the HTTP response status code will be 200

  • the HTTP body will contain an XML similar to the one below. The "Sid" is the unique identifier of the Leg and it will be useful for any future action on this leg

<?xml version="1.0" encoding="UTF-8"?>

<TwilioResponse>

<Leg>

<Sid>XXXXXXXXXXXXXXXXX</Sid>

<CallSid>XXXXXXXXXXXXXXX</CallSid>

<AccountSid>XXXXXXXX</AccountSid>

<EndUserNumber>XXXXXXXXX</EndUserNumber>

<Status>in-progress</Status>

<Origin>monitor</Origin>

<LastAction>barge</LastAction>

<DateCreated>2020-12-22 17:57:40</DateCreated>

<DateUpdated>2020-12-2217:57:40</DateUpdated>

<Uri>/v1/Accounts/XXXXXX/Calls/XXXXXXX/Legs</Uri>

</Leg>

</TwilioResponse>

 

On failure,

  • the HTTP response status code will be non-200.

  • the HTTP body will contain an XML (such as the one below) with details of why the request failed.

<?xml version="1.0" encoding="UTF-8"?>

<TwilioResponse>

   <RestException>

      <Status>400</Status>

      <Message>Invalid Parameter: PhoneNumber is missing or invalid</Message>

   </RestException>

</TwilioResponse>

 

 

Sample HTTP request 

 curl -H "Content-Type: application/json" --request POST -d '{"Action":"barge","TargetLegSid":"","PhoneNumber":"xxxx","StatusCallback":”","CustomField":"LegsCustom","StatusCallbackContentType":"application/json","StatusCallbackEvents[0]":"terminal"}' https://<Your_account_key>:<Your_account_token>@api.in.exotel.com/v1/Accounts/exotel30m/Calls/<CallSID>/Legs

 

 

StatusCallback


Exotel will perform an asynchronous HTTP request to the StatusCallback URL you have specified in your request (if any) once the call completes. List of parameters which will be sent as part of StatusCallback:

Sample StatusCallback payload for 'terminal' event:

 

"LegSid": "XXXXXXX"

"CallSid": "XXXXXX"

"AccountSid": "XXXXXX"

"DateCreated": "2021-02-08 19:33:59"

"DateUpdated": "2021-02-08 19:34:32"

"PhoneNumber": "XXXXXXXX"

"Status": "completed"

"Origin": "monitor"

"LastAction": "whisper"

"CustomField": "LegsCustom"

"EventType": "terminal"

 

Upgrade the monitor Leg

Once an action like Listen or Whisper , one can decide to perform the next action like Barge on the same leg create. To support this use case , API supports an upgrade capability where only below fields shown in the table below is accepted


An HTTP PUT request to  has to be made

https://<your_api_key>:<your_api_token>@<subdomain>/v1/Accounts/<your_sid>/Calls/<callSid>/Legs/<legSid>



The following are the PUT parameters:


Field

DataType

Mandatory

/Optional

Description

Action

string

Mandatory

New state for the call. Supported values whisper/ barge.


The only transition allowed are:
listen ->whisper
whisper-> barge
listen -> barge

TargetLegSid

string

Mandatory

The legSid to be upgraded. In this case will be the new leg created for monitor


Sample request 

curl -H "Content-Type: application/json" --request PUT -d '{"Action":"barge"}' https://<Your_API_Key>:<Your_API_Token>@api.in.exotel.com/v1/Accounts/<your_sid>/Calls/<Youd_Call_Sid>/Legs/<Monitor_leg_SID>

 

 

HTTP Response:

 

On success :- 

  • the HTTP response status code will be 200

  • the HTTP body will contain an XML similar to the one below.

<?xml version="1.0" encoding="UTF-8"?>

<TwilioResponse>

<Leg>

<Sid>XXXXXX</Sid>

<CallSid>XXXXXX</CallSid>

<AccountSid>XXXXX</AccountSid>

<EndUserNumber>XXXXXX</EndUserNumber>

<Status>in-progress</Status>

<Origin>monitor</Origin>

<LastAction>barge</LastAction>

<DateCreated>2020-12-24 10:55:54</DateCreated>

<DateUpdated>2020-12-24 10:56:53</DateUpdated>

<Uri>/v1/Accounts/XXXXXX/Calls/XXXX/Legs/XX</Uri></Leg></TwilioResponse>

 

 

On Failure :- 

  • the HTTP response status code will be non-200.

  • the HTTP body will contain an XML (such as the one below) with details of why the request failed.

 

<?xml version="1.0" encoding="UTF-8"?>

<TwilioResponse>

<RestException>

<Code>404</Code>

<Message>Given legSID does not exist. Please check the legSID passed</Message>

</RestException>

</TwilioResponse>

 

 

Get all legs on monitor leg creation success

After the monitor leg is created , developer can hit the Get the active legs endpoint to check the current status of all the ongoing legs 

 

Sample request :-

curl https://<your_api_key>:<your_api_token>

@api.in.exotel.com/v1/Accounts/<your_sid>/Calls/<>Call_SID/ActiveLegs.json

 

Sample response 

 

{

"Legs":[

{

"Sid":"XXXX",

"CallSid":"XXXX",

"AccountSid":"XXXX",

"EndUserNumber":"XXXX",

"Status":"in-progress",

"Origin":"outbound",

"LastAction":"",

"DateCreated":"2020-12-22 17:56:55",

"DateUpdated":"2020-12-22 17:57:02",

"Uri":"/v1/Accounts/XXXX/Calls/XXXX/ActiveLegs"

},

{

"Sid":"XXXX",

"CallSid":"XXXX",

"AccountSid":"XXXX",

"EndUserNumber":"XXXX",

"Status":"in-progress",

"Origin":"outbound-dial",

"LastAction":"",

"DateCreated":"2020-12-22 17:57:03",

"DateUpdated":"2020-12-22 17:57:03",

"Uri":"/v1/Accounts/XXXX/Calls/XXXX/ActiveLegs"

},

{

"Sid":"XXXX",

"CallSid":"XXXX",

"AccountSid":"XXXX",

"EndUserNumber":"XXXX",

"Status":"in-progress",

"Origin":"monitor",

"LastAction":"barge",

"DateCreated":"2020-12-22 17:57:40",

"DateUpdated":"2020-12-22 17:57:40",

"Uri":"/v1/Accounts/XXXX/Calls/XXXX/ActiveLegs"

}

]

}

 

A Typical call flow for LWB API in outbound API connecting agent to customer use case

 

 

Billing 

The supervisor leg will be charged as per the bill plan for calls applied to your account