Modifying Live Calls

Real time call modification allows you to interrupt an in-progress call and terminate it or have it begin processing RCML from a new URL. This is useful for any application where use async.

Live Call Modification API is supported only for calls created with Dial verb using a RCML application.

HTTP POST to a Call

To redirect or terminate a live call, you make an HTTP POST request to an in­-progress Call instance resource URI:

/call/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid} 
or
/call/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid}

The following parameters are available for you to POST request when modifying a phone call:

Request Parameters

Parameter	Description
Url	A valid URL that returns RCML. CallAPI will immediately redirect the call to the new RCML.
Method	The HTTP method CallAPI should use when requesting the above URL. Defaults to POST.
Status	Either canceled or completed. Specifying canceled will attempt to hang up calls that are queued or ringing but will not affect calls already in progress. Specifying completed will attempt to hang up a call even if it’s already in progress.
Mute	Either true or false. Setting value of this parameter to true will mute the call. Setting value of this parameter to false will unmute the call.

Call in-Progress

Any call that is currently ringing within a Dial verb is in-progress from the point of view of CallAPI, and thus you must use 'Status=completed' to cancel it.

Optional Parameters

You may POST the following parameters:

Request Parameters:

Parameter	Description
FallbackUrl	A URL that CallAPI will request if an error occurs requesting or executing the RCML at Url.
FallbackMethod	The HTTP method that CallAPI should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST.
StatusCallback	A URL that CallAPI will request when the call ends to notify your app.
StatusCallbackMethod	The HTTP method CallAPI should use when requesting the above URL. Defaults to POST.
MoveConnectedCallLeg	If True, CallAPI will move both call legs to the new URL.

Description:

A prerequisite for the Live Call Modification API is to know the CallSid ​of the call. The CallSid is generated by CallAPI for every incoming or outgoing call. When we create an outgoing call using the Calls REST API, CallAPI will generate the CallSid and the response will contain the CallSid. For an Incoming call, CallAPI will generate the CallSid, and will include it in the parameters of the GET or POST request to download the RCML from the application server. So the application server, will get the CallSid ​for this incoming call and can store it for later use.

Steps for an incoming call are the following:

• A new incoming call to CallAPI

• CallAPI generates CallSid and other parameters for this call

• CallAPI prepares GET/POST request and attaches the previously prepared parameters

• CallAPI sends the GET/POST request to the URL assigned to the DID called

• The Application server receives the GET/POST request

• The Application server stores the CallSid along with the rest of the parameters for later use

• The Application server prepares the response with the appropriate RCML for the given DID and send it back to CallAPI to process it

Given that we have the CallSid available, the next step to modify a live call is to prepare the new POST request to CallAPI with the URL of the new destination application.

Let’s assume that initially the Application server prepared an RCML that will connect the incoming call to Bob and that later Bob wants this call to be transferred to Alice. The Application Server will have to prepare a new RCML that will dial to Alice, and using the Live Call Modification API, will ask CallAPI to process this new RCML for the incoming call and thus will connect it to Alice.

Here are the steps:

• Incoming call - CallSid (1234567890)

• Application server - Store CallSid and other parameters, Prepare and send RCML that connects the call to Bob (using Dial verb)

• CallAPI process the given RCML and connects incoming call to Bob

• Bob wants to transfer the call to Alice and sends the request to Controller (application server)

• Application server: - Prepares new RCML with a given URL: http://app.server/CallToAlice that using Dial will dial to Alice - Uses Live Call Modification prepares a new POST request: https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/YOUR_CALL_SID - in the POST requests adds the following parameters: Url="http://app.server/CallToAlice"

• CallAPI processes this Live Call Modification request and redirects the incoming call to the new RCML application (to the new URL)

• Eventually the incoming call will be connected to Alice.

Similarly the application server can change an incoming call to Bob to a conference call where more participants can be added later. Given that application server already knows the CallSid for the incoming call to Bob.

• Prepare a new RCML for the Dial Conference

• Prepare new POST Live Call Modification request for the incoming call to be connected to the new url (that will dial to the conference)

• Prepare new outgoing call request using the Calls Rest API that will connect Bob to the conference application URL: https://v1.api19.com/call/2012-04-24/Accounts/ACCOUNT_SID/Calls` pass the following parameters: From=INCOMING_CALL_ID To=client:bob Url=CONFERENCE_APPLICATION_URL;

• Later the application server can create more outgoing call requests, similar to the one above, to invite other clients, SIP URLs or PSTN numbers to the conference call.