Call Redirection via the Twilio REST API

Call Redirection via the Twilio REST API

Twilio is excited to announce the addition of asynchronous call redirection to the Twilio REST API.  This feature opens a wide range of advanced call queuing, call center, and enterprise uses.   Using the call redirect API, you can interrupt an in-progress call and have it begin executing a new TwiML document of your choice, simply by POSTing to the Call Instance Resource.

This API gives you realtime control over running calls.  You can put calls in and out of hold music,  transfer a call from one <Dial> to another, hangup a call and so forth – all by making a simple REST API request.

Placing the Caller on Hold

Here is a simple example:

Lets say you receive an incoming call and want to put the caller on hold until someone can answer.  You can simply drop them into a TwiML document like this:

<Response>
<Say> Thank you for calling, a representative will be with you shortly</Say>
<Play loop="100">http://www.mydomain.foo/hold-music.mp3</Play>
</Response>

The caller will sit in a loop of hold music, patiently waiting.

Taking a Caller Off Hold

When a representative becomes available or other external event to occurs, your Twilio application can issue the following REST API request:

POST https://api.twilio.com/2008-08-01/Account/{YourAccountSid}/Calls/{WaitingCallersCallSid}
CurrentUrl=http://www.mydomain.com/dial-representitive

This will interrupt the looping Play verb and begin executing the following "dial-representive" TwiML for the caller.

<Response>
<Dial>415-555-6666</Dial>
</Response>

The end result is that the caller has been removed from the <Play> loop and placed into a <Dial>, taking he or she off hold and connecting the call to the representative at 415-555-6666.

Hanging Up on the Caller

If instead you wanted to hang up on the caller, you could make a similar REST API request which redirects the call to this TwiML document:

<Response>
<Say>Thank you for calling.  Goodbye</Say>
<Hangup/>
</Response>

Simple as that!   For more information on this feature, see the "Redirect a Call" section of the REST API documentation. We also have example code for a simple call queue in our HowTo section.