Twilio
Download:
twilio-documentation.zip

Call Queue

The Call Queue demo shows how to use Twilio's call redirection feature to construct a simple call queuing system. The demo illustrates how to take an in-progress call and place it on hold, then take the same call out of hold, just by making a call to the REST Call Redirect

The demo works as follows. A user visits a webpage, enters a phone number in the form and hits submit. When the user answers their phone, they are greeted and put into hold music. The webpage changes to display an "Accept Call" button. At any time, they can press the "Accept Call" button, which causes the web application to make a REST request to Twilio, telling it to interrupt the call and have it begin executing a new url.
In this case, Twilio redirect the call from sitting in hold music to a TwiML script instructing it to dial the Weather By Phone demo. This how-to could be easily modified to represent an incoming customer being placed on hold, while a customer service rep presses "Accept Call" to have the customer leave the hold music and Dial the rep's phone.

Concepts

This demo shows how to make outgoing calls using the Twilio REST API and how to use the Twilio REST API to asynchronously control what URL is executing during the call.

Try

Visit http://demo.twilio.com/callqueue, enter your phone number and click the Call button.

Download

callqueue.zip

Implementation

  • 1

    • The index page is a simple form that accepts a phone number from the user.

      howtos/callqueue/index.php
      <html>
<head>
<title>Call Queue Demo</title>
</head>
<body>
<H1>Call Queue Demo</H1>
<?php

if(strlen($_REQUEST['msg'])){
?>
<div>
<%=htmlentities($_REQUEST['msg'])%>
</div>
<?php
}


?>
<div style="width:550px"><p>
Call redirection allows you to change what URL is currently executing on your call, simply by making a REST request to Twilio. 
With call redirection, you can asynchronously modify how your call behaves.  To illustrate how this works, we are going to demonstrate a simple call queue in action. </p>
<p> 
Enter your phone number below and click the "Call Me" button.  Twilio will call you to start the demo.  When you answer the call, you will be greeted and put on hold.  On the next
page you will be given button to remove the call from hold.   
</p>
<form method="post" action="make_call.php">
	<input type="text" name="call_phonenumber">
	<input type="submit" value="Call me">
</form>
</div>

</body>
</html>

      The user enters a phone number and presses the Call button. The browser requests the makecall.php page which makes a POST request to the Twilio REST URL /2008-08-01/Accounts/ACCOUNT_SID/Calls (where ACCOUNT_SID is your Twilio account identifier) which initiates an outgoing call. A CallSid uniquely identifying the call is returned, which the code passes as a query parameter for later use.

      To make the REST call we take advantage of the free PHP REST API library provided by Twilio. It simplifies the the process of making HTTPS requests to Twilio and processing the responses. You can download a copy of the of the PHP REST library here. NOTE: If you would like to copy and use the code on this page there are several account specific variables you will need to fill in including AccountSid, AuthToken, and CallerID. For more information on making outgoing calls take a look at the REST Quickstart.

      howtos/callqueue/make_call.php
      <?php
require "twilio.php";

//load your account settings from config.php
require "config.php";


if(strlen($_POST['call_phonenumber'])){
	$call_phonenumber = preg_replace("/[^0-9]/","",$_POST['call_phonenumber']);
	
	/* Instantiate a new Twilio Rest Client */
	$client = new TwilioRestClient($AccountSid, $AuthToken);


	$response = $client->request("/$ApiVersion/Accounts/$AccountSid/Calls", "POST", array(
                "Caller" => $CallerID, // Outgoing Caller ID you have previously validated with Twilio
                "Called" => $call_phonenumber, // The phone number you wish to dial
                "Url" => $url."intro_twiml.php", // the URL of the web application on your server that will handle the call when it connects
                "Timeout"=>30
	));

	if($response->IsError) {
		$err = urlencode($response->ErrorMessage);
   		header("Location: index.php?msg=$err");
    	die;
	} else {
		/* redirect back to the main page with CallSid */
		$msg = urlencode("Calling... ".$call_phone_number);
		header("Location: control_panel.php?msg=$msg&CallSid=".$response->ResponseXml->Call->Sid);
    	die;
	}
	
}
?>

      After initiating the call or throwing an error, the server redirects the web browser back to the main control page, queue.php.

  • 2

    • When the call is answered, Twilio makes an HTTP request to the intro_twiml.php page the link to which was specified as part of the REST request.

  • 3

    • The web server sends back a TwiML document, intro_twiml.php. This document greets the person on the phone, and plays them hold music until they are removed from the queue.

      howtos/callqueue/intro_twiml.php
      <Response>
<Say>Hello, thank you for calling the Twilio call redirection demo.</Say>
<Say>You will be put into a hold queue until you click the Accept Call button on the demo site.</Say>
<!-- 
        Chopin Nocturne 15.2
        paul cantrell
        Creative Commons Attribution-Share Alike 2.5 Generic License 
        http://creativecommons.org/licenses/by-sa/2.5/
        http://innig.net/music/inthehands/2005/11/12/105/
-->
<Play>ith_chopin-15-2_sample.wav</Play>
</Response>

  • 4

    • When the user wants to remove their call from the hold queue, they press the Accept Call button. The web application then makes an HTTP POST to the current call's REST Resource URL, /2008-08-01/Accounts/ACCOUNT_SID/Calls/CALL_SID. CALL_SID is the value that was returned by the outgoing call request in step #1. In the body of this POST, we pass the parameter CurrentUrl, which points at accept_twiml.php.
      This is the URL we want the call to begin executing. See REST Call Redirect for more details.

      howtos/callqueue/accept.php
      <?php
require "twilio.php";
require "config.php";

if(strlen($_POST['CallSid'])){
        $callSid = $_POST['CallSid'];
        /* Instantiate a new Twilio Rest Client */
        $client = new TwilioRestClient($AccountSid, $AuthToken);


        $response = $client->request("/$ApiVersion/Accounts/$AccountSid/Calls/$callSid", "POST", array(
                "CurrentUrl" => $url."accept_twiml.php" // the URL you want to redirect to
    	));

        if($response->IsError) {
                $err = urlencode($response->ErrorMessage);
                header("Location: accept.php?CallSid=$callSid&msg=$err");
        die;
        } else {
                /* redirect back to the main page with CallSid */
                $msg = urlencode("Call Removed from Queue... ");
                header("Location: completed.php?CallSid=$callSid&msg=$msg");
        die;
        }

}

?>

  • 5

    • When Twilio receives the call redirect REST request, it makes an HTTP request to the URL passed via CurrentUrl (accept_twiml.php).

  • 6

    • When your webserver responds, Twilio stops executing intro_twiml.php and begins executing accept_twiml.php instead. For this demo, this causes Twilio to connect the call on hold to our weather by phone app at (866) 583-8121.

      howtos/callqueue/accept_twiml.php
      <Response>
<Say>Thank you for waiting, connecting you to the weather department now</Say>
<Dial>(866) 583-8121</Dial>
<Hangup/>
</Response>