IVR: The Basics

IVRs (interactive voice response) are automated phone systems that can facilitate communication between callers and businesses. If you've ever dialed your credit card company to check on a balance after responding to a series of automated prompts, you've used an IVR. Using any web language of your choice, you can easily create powerful IVRs for your business using Twilio's API's.

Usage

A Twilio phone number is provisioned and its Voice URL is set to the handle-incoming-call.xml script. When a call is made to that number, Twilio makes a web request to your application's Voice URL for instructions on how to handle the call.

For this tutorial, we'll assume that we're a fictitious shipping company. When a customer dials our Twilio phone number, our IVR will read back a menu of options, gather their input, and return the store hours.

Concepts

This demo shows how to create a simple phone tree using Twilio's <Say>, <Gather>, and <Dial> verbs.

Download

IVR.zip

Implementation

• Customer dials a Twilio number and Twilio POSTs information to your application. 1
• Your server outputs menu TwiML that prompts the customer for input. 2
• Twilio reads the prompt, gathers the customer input, and sends it to your application. 3
• Your server processes the customer input and outputs the store hours. 4

• 1

  • Our Twilio number's Voice URL is set to handle-incoming-call.xml. When someone calls the number, Twilio will request this page with the standard TwiML request parameters.

• 2

  • The application responds in TwiML to Twilio's request using the Say and Gather verbs. This instructs Twilio to prompt the customer and gather their input.
  • howtos/ivr/code/ivrs-the-basics/handle-incoming-call.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
    	<Gather action="handle-user-input.php" numDigits="1">
    		<Say>Welcome to TPS.</Say>
    		<Say>For store hours, press 1.</Say>
    		<Say>To speak to an agent, press 2.</Say>
    		<Say>To check your package status, press 3.</Say>
    	</Gather>
    	<!-- If customer doesn't input anything, prompt and try again. -->
    	<Say>Sorry, I didn't get your response.</Say>
    	<Redirect>handle-incoming-call.xml</Redirect>
    </Response>
        

• 3

  • The customer pushes 1 for store hours. This input is then sent back to your application as an HTTP request.
  • PHP
  • C#

  • howtos/ivr/code/ivrs-the-basics/handle-user-input.php

    	$user_pushed = (int) $_REQUEST['Digits'];
        

  • howtos/ivr/code/ivrs-the-basics/handle-user-input.cshtml

        int user_pushed = int.Parse(Request["Digits"]);
        

• 4

  • Your application parses the request and returns the store hours.
  • PHP
  • C#

  • howtos/ivr/code/ivrs-the-basics/handle-user-input.php

    <?php
    	header('Content-type: text/xml');
    	echo '<?xml version="1.0" encoding="UTF-8"?>';
    
    	echo '<Response>';
    
    	# @start snippet
    	$user_pushed = (int) $_REQUEST['Digits'];
    	# @end snippet
    
    	if ($user_pushed == 1)
    	{
    		echo '<Say>Our store hours are 8 AM to 8 PM everyday.</Say>';
    	}
    	else {
    		// We'll implement the rest of the functionality in the 
    		// following sections.
    		echo "<Say>Sorry, I can't do that yet.</Say>";
    		echo '<Redirect>handle-incoming-call.php</Redirect>';
    	}
    
    	echo '</Response>';
    ?>
        

  • howtos/ivr/code/ivrs-the-basics/handle-user-input.cshtml

    @{
        Response.ContentType = "text/xml";
        
        var twiml = new Twilio.TwiML.TwilioResponse();
        
        // @start snippet
        int user_pushed = int.Parse(Request["Digits"]);
        // @end snippet
        
        if (user_pushed == 1)
        {
            twiml.Say("Our store hours are 8 AM to 8 PM everyday.");
        }
        else 
        {
            // We'll implement the rest of the functionality in the 
            // following sections.
            twiml.Say("Sorry, I can't do that yet.");
            twiml.Redirect("handle-incoming-call.xml", "GET");
        }
    }
    @Html.Raw(twiml.ToString())    

This is part one of a five part series on building IVRs using Twilio's API. When you're ready continue on to the next section:

• Section 1.2 - Extensions