Listen Whisper Barge (LWB) API (Beta)

Video:

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

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.
Create the monitor leg: Once the leg is identified, one needs 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 on the API.

NOTE: To enable this API in your account, please reach out to hello@exotel.in

1. 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 of your account.
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
Replace <CallSid> with the "Call Sid of your ongoing call"

<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",

"PhoneNumber":"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",

"PhoneNumber":"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 is the Sid if the Leg identifier is to be used in creating the monitor action on a leg.

On Failure,

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

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

</RestException>

</TwilioResponse>sh-3.2#

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 the Exotel platform to the 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	A 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	An 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"?>

<Leg>

<Sid>XXXXXXXXXXXXXXXXX</Sid>

<CallSid>XXXXXXXXXXXXXXX</CallSid>

<AccountSid>XXXXXXXX</AccountSid>

<PhoneNumber>XXXXXXXXX</PhoneNumber>

<Status>in-progress</Status>

<Origin>monitor</Origin>

<LastAction>barge</LastAction>

<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"?>

<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 that 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"

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

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

"PhoneNumber": "XXXXXXXX"

"Status": "completed"

"OnCallDuration": "52"

"Origin": "monitor"

"LastAction": "whisper"

"CustomField": "LegsCustom"

"EventType": "terminal"

3. 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 created. To support this use case, API supports an upgrade capability where only below fields shown in the table below are accepted

Please note that the monitor call leg should not be disconnected while performing this PUT request. Else you will receive an error that the Leg sid does not exist.

An HTTP PUT request to has to be made

https://<your_api_key>:<your_api_token>@<subdomain>/v1/Accounts/<your_sid>/Calls/<CallSid>/Legs/<Monitor_leg_SID>

Replace <your_api_key> and <your_api_token> with the API key and token of your account.
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
Replace <CallSid> with your “Call sid of the ongoing call”
Replace <Monitor_leg_SID> with your “Leg sid of the Monitor API”

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

The following are the PUT parameters:

Field

DataType

Mandatory

/Optional

Description

Action

string

Mandatory

A new state for the call. Supported values whisper/ barge.

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

TargetLegSid

string

Mandatory

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

Mandatory if Action = whisper
Optional if Action = barge

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"?>

<Leg>

<Sid>XXXXXX</Sid>

<CallSid>XXXXXX</CallSid>

<AccountSid>XXXXX</AccountSid>

<PhoneNumber>XXXXXX</PhoneNumber>

<Status>in-progress</Status>

<Origin>monitor</Origin>

<LastAction>barge</LastAction>

<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"?>

<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, the 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",

"PhoneNumber":"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",

"PhoneNumber":"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

Call Disconnect API <Hangup>

High-Level Approach

Hangup action will be enabled in the Legs API.
Customer to query legs for the callSid and perform hangup action on leg

API Contract:

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

The following are the PUT parameters:

Field	Mandatory/ Optional	DataType	Values
Action	Mandatory	string	“hangup”

Sample Request

curl --location --request PUT 'http://<API_KEY>:<API_Token>@api.in.exotel.com/v1/Accounts/<Account_SID>/Calls/<Call_SID>/Legs/<Leg_SDI>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'Action=hangup'

Sample Response: JSON Response (Default response type is XML)

{
"legs": {
"Sid": "80de40c29dXXX83b485f8d4168c",
"CallSid": "9aeaea05XXXX268d3c872168c",
"AccountSid": "exXXXt",
"PhoneNumber": "0720XX45365",
"Status": "in-progress",
"Origin": "outbound",
"LastAction": "hangup",
"DateCreated": "2022-08-12 12:14:44",
"DateUpdated": "2022-08-12 12:14:58",
"StartTime": "2022-08-12 12:14:56",
"ExoPhone": "080XXX92531",
"BackupExoPhone": "0804XXX2531",
"Uri": "/v1/Accounts/exXXXlt/Calls/9aeaea053872168c/Legs/80de40c29d3b485f8d4168c"
}
}

Sample Response : XML Response

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<Legs>
<Sid>80de40c29d9d8d4168c</Sid>
<CallSid>9aeaea053de5268d3c872168c</CallSid>
<AccountSid>abjcw</AccountSid>
<PhoneNumber>072XX45365</PhoneNumber>
<Status>in-progress</Status>
<Origin>outbound</Origin>
<LastAction>hangup</LastAction>
<DateCreated>2022-08-12 12:14:44</DateCreated>
<DateUpdated>2022-08-12 12:14:58</DateUpdated>
<StartTime>2022-08-12 12:14:56</StartTime>
<ExoPhone>0804XX2531</ExoPhone>
<BackupExoPhone>0804XX92531</BackupExoPhone>
<Uri>/v1/Accounts/sdcds/Calls/9aeaea053de5268d3c872168c/Legs/80de40c29d9d645bd185f8d4168c</Uri>
</Legs>
</TwilioResponse>

Sample Failure Response: XML

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<RestException>
<Code>404</Code>
<Message>Not Found</Message>
</RestException>
</TwilioResponse>

Sample Failure Response: JSON

{
"RestException": {
"Code": 404,
"Message": "Not Found"
}
}

Billing

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

If you have any questions or concerns, please connect with us using the chat widget on your Exotel Dashboard or Whatsapp us on 08088919888

Exotel Support Center

How can we help you today?

How to perform Listen Whisper Barge using LWB API Print

Listen Whisper Barge (LWB) API (Beta)

1. Get the active legs of the ongoing call

2. Create the monitor leg

3. Upgrade the monitor Leg

Get all legs on monitor leg creation success

How can we help you today?

How to perform Listen Whisper Barge using LWB API Print

Listen Whisper Barge (LWB) API (Beta)

1. Get the active legs of the ongoing call

2. Create the monitor leg

3. Upgrade the monitor Leg

Get all legs on monitor leg creation success

Related Articles