How to perform Listen Whisper Barge using LWB API

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 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"?> \<twilioresponse> \<restexception> \<code>404\</code> \<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"?> \<twilioresponse> \<leg> \<sid>xxxxxxxxxxxxxxxxx\</sid> \<callsid>xxxxxxxxxxxxxxx\</callsid> \<accountsid>xxxxxxxx\</accountsid> \<phonenumber>xxxxxxxxx\</phonenumber> \<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> \<starttime>2020 12 2217 57 40\</starttime> \<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 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"?> \<twilioresponse> \<leg> \<sid>xxxxxx\</sid> \<callsid>xxxxxx\</callsid> \<accountsid>xxxxx\</accountsid> \<phonenumber>xxxxxx\</phonenumber> \<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> \<starttime>2021 02 08 19 33 59\</starttime> \<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, 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