REST API: Modifying Live Calls

Realtime call modification allows you to interrupt an in-progress call and terminate it or have it begin processing TwiML from a new URL. This is useful for any application where you want to asynchronously change the behavior of a running call. For example: hold music, call queues, transferring calls, forcing hangup, etc.

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:


POST Parameters

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

UrlA valid URL that returns TwiML. Twilio will immediately redirect the call to the new TwiML.
MethodThe HTTP method Twilio should use when requesting the above URL. Defaults to POST.
StatusEither canceled or completed. Specifying canceled will attempt to hangup calls that are queued or ringing but not affect calls already in progress. Specifying completed will attempt to hang up a call even if it's already in progress.

Note that any call which is currently ringing within a <Dial> verb is in-progress from the point of view of Twilio, and thus you must use 'Status=completed' to cancel it.

Optional Parameters

You may POST the following parameters:

FallbackUrlA URL that Twilio will request if an error occurs requesting or executing the TwiML at Url.
FallbackMethodThe HTTP method that Twilio should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST.
StatusCallbackA URL that Twilio will request when the call ends to notify your app.
StatusCallbackMethodThe HTTP method Twilio should use when requesting the above URL. Defaults to POST.


Example 1

Redirect a running call to a new URL

Example 2

Terminate a running call