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 you want to asynchron
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:
1
/call/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid}
2
or
3
/call/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid}
Copied!
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. teleapi will immediately redirect the call to the new RCML.
Method
The HTTP method teleapi 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 teleapi, 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 teleapi will request if an error occurs requesting or executing the RCML at Url.
FallbackMethod
The HTTP method that teleapi should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST.
StatusCallback
A URL that teleapi will request when the call ends to notify your app.
StatusCallbackMethod
The HTTP method teleapi should use when requesting the above URL. Defaults to POST.
MoveConnectedCallLeg
If True, teleapi 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 teleapi for every incoming or outgoing call. When we create an outgoing call using the Calls REST API, teleapi will generate the CallSid and the response will contain the CallSid. For an Incoming call, teleapi 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 teleapi
  • teleapi generates CallSid and other parameters for this call
  • teleapi prepares GET/POST request and attaches the previously prepared parameters
  • teleapi 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 teleapi 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 teleapi 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 teleapi 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)
  • teleapi 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://calls.teleapi.net/call/2012-04-24/Accounts/ACCOUNT_SID/Calls/YOUR_CALL_SID - in the POST requests adds the following parameters: Url="http://app.server/CallToAlice"
  • teleapi 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://calls.teleapi.net/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.