Get Started

Call Screening

Many times a voice application will have a list of numbers to call in a specific order. If the first number doesn't pick up, then a second number should be called, and so on. However, if a number goes to voicemail, how should the application respond? Our solution is to prompt the called number to accept the call. If no answer is received, we move on to the next phone number.

Usage

A user receives a call and is prompted to accept by pressing any key. If no input is detected, we call the next number on the list.

Concepts

This demo demonstrates creating TwiML call logic using the <Dial>, <Number>, and <Gather> verbs.

Download

callscreen.zip

Implementation

  • 1

    Twilio processes the call and sends CallerID to attempt_call.php

  • 2

    • We get the first two phone numbers to be called from the GET request using the $_REQUEST variable. Before making the call, we make sure that we have a valid number and that a previous call wasn't completed. Notice that the Dial action's attribute points back to attempt_call.php, but with the second number as the main number instead.

      • howtos/callscreen/attempt_call.php
        <?php 
        
        // Set the numbers to call
        $numbers = array("<number to call 1>", "<number to call 2>", "<number to call n>");
        $number_index = isset($_REQUEST['number_index']) ? $_REQUEST['number_index'] : "0";
        $DialCallStatus = isset($_REQUEST['DialCallStatus']) ? $_REQUEST['DialCallStatus'] : "";
        
        header("content-type: text/xml"); 
        
        // Check the status of the call and 
        // that there is a valid number to call
        
        if($DialCallStatus!="completed" && $number_index<count($numbers)){ 
        ?>
        	<Response>
        	<Dial action="attempt_call.php?number_index=<?php echo $number_index+1 ?>">
        		<Number url="screen_for_machine.php">
        		<?php echo $numbers[$number_index] ?>
        		</Number>
        	</Dial>
        	</Response>
        <?php
        } else {
        ?>
        	<Response>
        		<Hangup/>
        	</Response>
        <?php
        }
        ?>    

      To make this logic work, we take advantage of Dial's action attribute and Number's url attribute. When the call is connected, Number will execute the url on the caller's side. Once the call is finished, the Dial will make a POST request to its action url. All of this functionality is discussed in detail in Dial's Documentation

  • 3

    Twilio calls the given number. Once that number picks up, Twilio sends a request to screen_for_machine.php

  • 4

    • We output TwiML that asks the user to input any number, which activates the Gather's action url

      • howtos/callscreen/screen_for_machine.xml
        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
        	<Gather action="complete_call.xml">
        		<Say>Press any key to accept this call</Say>
        	</Gather>
        	<Hangup/>
        </Response>    
  • 5

    Twilio completes the call, sending CallStatus to attempt_call.php. The "number" parameter is the second number we specified at the beginning of the call. If the user pressed a button, Twilio will also request complete_call.php

  • 6

    • complete_call.php simply notifies the user that the call is being connected

      If call status is "completed", the call is over and we tell Twilio to hangup the phone. However, if the call status is "no-answer", attempt_call.php will try to call the next number which was given, starting the entire call cycle all over again. Note: if no number is defined, we simply hangup.

      • howtos/callscreen/attempt_call.php
        <?php 
        
        // Set the numbers to call
        $numbers = array("<number to call 1>", "<number to call 2>", "<number to call n>");
        $number_index = isset($_REQUEST['number_index']) ? $_REQUEST['number_index'] : "0";
        $DialCallStatus = isset($_REQUEST['DialCallStatus']) ? $_REQUEST['DialCallStatus'] : "";
        
        header("content-type: text/xml"); 
        
        // Check the status of the call and 
        // that there is a valid number to call
        
        if($DialCallStatus!="completed" && $number_index<count($numbers)){ 
        ?>
        	<Response>
        	<Dial action="attempt_call.php?number_index=<?php echo $number_index+1 ?>">
        		<Number url="screen_for_machine.php">
        		<?php echo $numbers[$number_index] ?>
        		</Number>
        	</Dial>
        	</Response>
        <?php
        } else {
        ?>
        	<Response>
        		<Hangup/>
        	</Response>
        <?php
        }
        ?>