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:

/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}

POST Parameters

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

Parameter Description
Url A valid URL that returns TwiML. Twilio will immediately redirect the call to the new TwiML.
Method The HTTP method Twilio should use when requesting the above URL. Defaults to POST.
Status Either 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 currenty 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.

Examples

Example 1

Redirect a running call to a new URL

Try it now

  • POST /2010-04-01/Accounts/AC5ef87.../Calls/CAe1644a7eed5088b159577c5802d8be38

    Url=http://www.myapp.com/myhandler.php&Method=POST

    <TwilioResponse>
    <Call>
        <Sid>CAe1644a7eed5088b159577c5802d8be38</Sid>
        <DateCreated>Tue, 10 Aug 2010 08:02:17 +0000</DateCreated>
        <DateUpdated>Tue, 10 Aug 2010 08:02:47 +0000</DateUpdated>
        <ParentCallSid/>
        <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
        <To>+14153855708</To>
        <From>+14158141819</From>
        <PhoneNumberSid></PhoneNumberSid>
        <Status>in-progress</Status>
        <StartTime>Tue, 10 Aug 2010 08:02:31 +0000</StartTime>
        <EndTime>Tue, 10 Aug 2010 08:02:47 +0000</EndTime>
        <Duration>16</Duration>
        <Price>-0.03000</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy/>
        <ApiVersion>2010-04-01</ApiVersion>
        <ForwardedFrom/>
        <CallerName/>
        <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38</Uri>
        <SubresourceUris>
            <Notifications>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Notifications</Notifications>
            <Recordings>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Recordings</Recordings>
        </SubresourceUris>
    </Call>
</TwilioResponse>
Example 2

Terminate a running call

Try it now

  • POST /2010-04-01/Accounts/AC5ef87.../Calls/CAe1644a7eed5088b159577c5802d8be38

    Status=completed

    <TwilioResponse>
    <Call>
        <Sid>CAe1644a7eed5088b159577c5802d8be38</Sid>
        <DateCreated>Tue, 10 Aug 2010 08:02:17 +0000</DateCreated>
        <DateUpdated>Tue, 10 Aug 2010 08:02:47 +0000</DateUpdated>
        <ParentCallSid/>
        <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
        <To>+14153855708</To>
        <From>+14158141819</From>
        <PhoneNumberSid></PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>Tue, 10 Aug 2010 08:02:31 +0000</StartTime>
        <EndTime>Tue, 10 Aug 2010 08:02:47 +0000</EndTime>
        <Duration>16</Duration>
        <Price>-0.03000</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy/>
        <ApiVersion>2010-04-01</ApiVersion>
        <ForwardedFrom/>
        <CallerName/>
        <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38</Uri>
        <SubresourceUris>
            <Notifications>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Notifications</Notifications>
            <Recordings>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Recordings</Recordings>
        </SubresourceUris>
    </Call>
</TwilioResponse>