Simple Phone Menu

Twilio makes it easy to create automated phone menus. This HowTo shows you how to write a simple menu that a caller can navigate using the keypad on almost any phone.

Usage

A user calls and is greeted with a list of choices. For example, "For location, press 1". The user enters his/her choice on the telephone keypad, and the next list of choices or information is read. Rinse, repeat.

Concepts

This HowTo demonstrates creating TwiML call logic, with focus on the <Gather> verb.

Download

phonemenu.zip

Implementation

• Twilio receives a phone call to the menu number, and sends your app the call data. 1
• Your server outputs menu TwiML based on that call data. 2
• Menu choices are read, and the user picks an item. 3
• Your server outputs more menu TwiML based on the digits gathered. Repeat. 4

• 1

  • Twilio receives a phone call to the menu's phone number, sending call data to the Voice URL you configured for that number. The script below handles requests to that URL.

• 2

  • The phone menu system relies on the use of nested <Say> verbs inside a <Gather> verb. This setup allows the caller to make a menu selection before listening to all of the options. For more information, see Example 2 in the <Gather> documentation.

    Each menu list has a name and a certain number of connections to other menu lists. These connections are represented via arrays. The key press associated with the menu item represents the index of the node name in the menu node array. For example, pressing 2 in the default node selects the location node. We can see that "location" has an index of 2 in the default array.

    • PHP
    • Java
    • CF
    • C#

    • howtos/phonemenu/phonemenu.php

      /* Define Menu */
      $web = array();
      $web['default'] = array('receptionist','hours', 'location', 'duck');
      $web['location'] = array('receptionist','east-bay', 'san-jose', 'marin');
      
      /* Get the menu node, index, and url */
      $node = $_REQUEST['node'];
      $index = (int) $_REQUEST['Digits'];
      $url = 'http://'.dirname($_SERVER["SERVER_NAME"].$_SERVER['PHP_SELF']).'/phonemenu.php';
      
      /* Check to make sure index is valid */
      if(isset($web[$node]) || count($web[$node]) >= $index && !is_null($_REQUEST['Digits']))
      	$destination = $web[$node][$index];
      else
      	$destination = NULL;
          

    • howtos/phonemenu/PhoneMenu.java

      		/* Define Menu */
      		String[] defaultMenu = {"receptionist","hours", "location", "duck"};
      		String[] locationMenu = {"receptionist","east-bay", "san-jose"};
      
              Map<String,String[]> menuDefinition = new HashMap<String,String[]>();
              menuDefinition.put("default", defaultMenu);
              menuDefinition.put("location", locationMenu);
      
              String destination;
      		/* Check to make sure index is valid */
      		if(index>=0 && node!=null && menuDefinition.get(node).length >= index)
      			destination = menuDefinition.get(node)[index];
      		else
      			destination = null;
          

    • howtos/phonemenu/phonemenu.cfm

      <!---  Define Menu  --->
      <cfset web = StructNew()>
      <cfset web["default"] = ["receptionist","hours", "location", "duck"]>
      <cfset web["location"] =["receptionist","east-bay", "san-jose", "marin"]>
      <cfset node = url.node> 
      <cfset index = form.Digits>
      <cfif isnumeric(index)>
      	<Cfset index=index+1> <!--- CF array index starts at 1 --->
      </cfif>
      <cfset url = "phonemenu.php">
       
      <cfif isnumeric(index) and index gte 0 and StructKeyExists(web,node)  >
          <cfset destination = web[node][index]>
      <cfelse>
          <cfset destination = "">
      </cfif>	
      
          

    • howtos/phonemenu/phonemenu.cshtml

          /* Define Menu */
          Dictionary<string, string[]> web = new Dictionary<string, string[]>() { 
              {"default",new string[] {"receptionist","hours", "location", "duck"} },
              {"location",new string[] {"receptionist","east-bay", "san-jose", "marin"} }
          };
      
          Uri cleanedUri = new Uri(Request.Url.GetComponents(UriComponents.AbsoluteUri & ~UriComponents.Port, UriFormat.UriEscaped));
          string baseUri = cleanedUri.AbsoluteUri.Remove(cleanedUri.AbsoluteUri.Length - cleanedUri.Segments.Last().Length);
       
          /* Get the menu node, index, and url */
          string node = Request["node"]!=null ? Request["node"] : "";    
          int index = Request["Digits"]!=null ? int.Parse(Request["Digits"]) : 0;
          
          string url = string.Format("{0}phonemenu.cshtml", baseUri);
       
          /* Check to make sure index is valid */
          string destination = string.Empty;    
          if( web.Keys.Contains(node) && web[node].Length >= index && Request["Digits"]!=null) {
              destination = web[node][index]; }
          else {
              destination = string.Empty; }
          

    The TwiML for each node lives in a large switch statement.

    • PHP
    • Java
    • CF
    • C#

    • howtos/phonemenu/phonemenu.php

      /* Render TwiML */
      header("content-type: text/xml");
      echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response>\n";
      switch($destination) {
      	case 'hours': ?>
      		<Say>Initech is open Monday through Friday, 9am to 5pm</Say>
      		<Say>Saturday, 10am to 3pm and closed on Sundays</Say>
      		<?php break;
      	case 'location': ?>
      		<Say>Initech is located at 101 4th St in San Francisco California</Say>
      		<Gather action="<?php echo 'http://' . dirname($_SERVER["SERVER_NAME"] .  $_SERVER['PHP_SELF']) . '/phonemenu.php?node=location'; ?>" numDigits="1">
      			<Say>For directions from the East Bay, press 1</Say>
      			<Say>For directions from San Jose, press 2</Say>
      		</Gather>
      		<?php break;
      	case 'east-bay': ?>
      		<Say>Take BART towards San Francisco / Milbrae. Get off on Powell Street. Walk a block down 4th street</Say>
      		<?php break;
      	case 'san-jose': ?>
      		<Say>Take Cal Train to the Milbrae BART station. Take any Bart train to Powell Street</Say>
      		<?php break;
      	case 'duck'; ?>
      		<Play>duck.mp3</Play>
      		<?php break;
      	case 'receptionist'; ?>
      		<Say>Please wait while we connect you</Say>
      		<Dial>NNNNNNNNNN</Dial>
      		<?php break;
      	default: ?>
      		<Gather action="<?php echo 'http://' . dirname($_SERVER["SERVER_NAME"] .  $_SERVER['PHP_SELF']) . '/phonemenu.php?node=default'; ?>" numDigits="1">
      			<Say>Hello and welcome to the Initech Phone Menu</Say>
      			<Say>For business hours, press 1</Say>
      			<Say>For directions, press 2</Say>
      			<Say>To hear a duck quack, press 3</Say>
      			<Say>To speak to a receptionist, press 0</Say>
      		</Gather>
      		<?php
      		break;
      }
          

    • howtos/phonemenu/PhoneMenu.java

      			if (destination=="receptionist"){
      		        Say say = new Say("Please wait while we connect you");
      		        Dial dial = new Dial("8583829141");
      		        response.append(say);
      		        response.append(dial);
      			} else if (destination=="hours"){
      				Say say = new Say("Initech is open Monday through Friday, 9am to 5pm, Saturday, 10am to 3pm and closed on Sundays.");
      				response.append(say);
      			} else if (destination=="location"){
      				Say say = new Say("Initech is located at 101 4th St in San Francisco California");
      				response.append(say);
      			} else if (destination=="duck"){
      				Play play = new Play("duck.mp3");
      				response.append(play);
      			} else if (destination=="receptionist"){
      				Say say = new Say("Initech is open Monday through Friday, 9am to 5pm, Saturday, 10am to 3pm and closed on Sundays.");
      				response.append(say);
      			} else if (destination=="east-bay"){
      				Say say = new Say("Take BART towards San Francisco / Milbrae. Get off on Powell Street. Walk a block down 4th street.");
      				response.append(say);
      			} else if (destination=="san-jose"){
      				Say say = new Say("Take Cal Train to the Milbrae BART station. Take any Bart train to Powell Street.");
      				response.append(say);
      			} else { 
      				// no destination
      				Gather gather = new Gather();
      				gather.setAction(BASEURL + "?node=default");
      				gather.setNumDigits(1);
      				Say say = new Say("Hello and welcome to the Initech Phone Menu. For business hours, press 1.  For directions, press 2.  To hear a duck quack, press 3 To speak to a receptionist, press 0");
      				gather.append(say);
      				response.append(gather);
      			}            
      			
      	    	if (destination=="location"){
      	    		Gather gather = new Gather();
      	    		gather.setAction(BASEURL + "?node=location");
      	    		gather.setNumDigits(1);
      	    		response.append(gather);
      	    		gather.append (new Say ("For directions from the East Bay, press 1. For directions from San Jose, press 2."));
      	    	}
      	    	
          

    • howtos/phonemenu/phonemenu.cfm

      <!---  Render TwiML  --->
      <CFContent type="text/xml">
      <cfsetting showdebugoutput="no">
      <cfinclude template="TwilioSettings.cfm" />
      <cfset t = createObject("component", "TwilioLib").init(AccountSid, AuthToken) />
      <cfset r = t.newResponse() />
      
      <cfswitch expression="#destination#">
      	<cfcase value="hours">
      		<cfset r.Say("Initech is open Monday through Friday, 9am to 5pm") />
      		<cfset r.Say("Saturday, 10am to 3pm and closed on Sundays") />
      	</cfcase>
      	<cfcase value="location">
      		<cfset r.Say("Initech is located at 101 4th St in San Francisco California") />
      		<cfset r.gather(numDigits="1", Action="phonemenu.cfm?node=location") />
      		<cfset r.say(body="For directions from the East Bay, press 1", voice="man", childOf="gather") />
      		<cfset r.say(body="For directions from San Jose, press 2", voice="man", childOf="gather") />
      	</cfcase>
      	<cfcase value="east-bay">
      		<cfset r.Say("Take BART towards San Francisco / Milbrae. Get off on Powell Street. Walk a block down 4th street") />
      	</cfcase>
      	<cfcase value="san-jose">
      		<cfset r.Say("Take Cal Train to the Milbrae BART station. Take any Bart train to Powell Street") />
      	</cfcase>
      	<cfcase value="duck">
      		<cfset r.Play("duck.mp3") />
      	</cfcase>
      	<cfcase value="receptionist">
      		<cfset r.Say("Please wait while we connect you") />
      		<cfset r.Dial("NNN") />
      	</cfcase>
      	<cfdefaultcase>
      		<cfset r.gather(numDigits="1", Action="phonemenu.cfm?node=default") />
      		<cfset r.say(body="Hello and welcome to the Ini tech Phone Menu", voice="man", childOf="gather") />
      		<cfset r.say(body="For business hours, press 1", voice="man", childOf="gather") />
      		<cfset r.say(body="For directions, press 2", voice="man", childOf="gather") />
      		<cfset r.say(body="To hear a duck quack, press 3", voice="man", childOf="gather") />
      		<cfset r.say(body="To speak to a receptionist, press 0", voice="man", childOf="gather") />
      	</cfdefaultcase>
      </cfswitch>
          

    • howtos/phonemenu/phonemenu.cshtml

          /* Render TwiML */
          Response.ContentType = "text/xml";
          var twiml = new Twilio.TwiML.TwilioResponse();
      
          switch (destination)
          {
              case "hours":
                  twiml.Say("Initech is open Monday through Friday, 9am to 5pm");
                  twiml.Say("Saturday, 10am to 3pm and closed on Sundays");
                  break;
              case "location":
                  twiml.Say("Initech is located at 101 4th St in San Francisco California");
                  twiml.BeginGather(new { action = "phonemenu.cshtml?node=location", numDigits = "1" })
                      .Say("For directions from the East Bay, press 1")
                      .Say("For directions from San Jose, press 2");
                  twiml.EndGather();
                  break;
              case "east-bay":
                  twiml.Say("Take BART towards San Francisco / Milbrae. Get off on Powell Street. Walk a block down 4th street");
                  break;
              case "san-jose":
                  twiml.Say("Take Cal Train to the Milbrae BART station. Take any Bart train to Powell Street");
                  break;
              case "duck":
                  twiml.Play("duck.mp3");
                  break;
              case "receptionist":
                  twiml.Say("Please wait while we connect you");
                  twiml.Dial("NNNNNNNNNN");
                  break;
              default:
                  twiml.BeginGather(new { action = "phonemenu.cshtml?node=default", numDigits = "1" })
                      .Say("Hello and welcome to the Initech Phone Menu")
                      .Say("For business hours, press 1")
                      .Say("For directions, press 2")
                      .Say("To hear a duck quack, press 3")
                      .Say("To speak to a receptionist, press 0");
                  twiml.EndGather();
                  break;
          }
          

    Unless otherwise specified, each menu item ends in TwiML that redirects back to the main menu, ensuring that the user does not leave the menu unless he or she hangs up the phone.

    • PHP
    • Java
    • CF
    • C#

    • howtos/phonemenu/phonemenu.php

      if($destination && $destination != 'receptionist') { ?>
      	<Pause/>
      	<Say>Main Menu</Say>
      	<Redirect><?php echo 'http://' . dirname($_SERVER["SERVER_NAME"] .  $_SERVER['PHP_SELF']) . '/phonemenu.php' ?></Redirect>
      <?php }
          

    • howtos/phonemenu/PhoneMenu.java

      	    	if (destination!=null && destination!="receptionist") {
      				Pause pause = new Pause();
      				pause.setLength(2);
      				response.append(pause);
      				Say menuSay = new Say("Main Menu");
      				response.append(menuSay);
      				Redirect redirect = new Redirect(BASEURL);
      				response.append(redirect);
      			}
          

    • howtos/phonemenu/phonemenu.cfm

      <cfif destination is not "receptionist">
      	<cfset r.pause(length="1")>
      	<cfset r.Say("Main Menu") />
      	<cfset r.redirect("phonemenu.cfm")>
      </cfif>
          

    • howtos/phonemenu/phonemenu.cshtml

          if (destination != String.Empty && destination != "receptionist")
          {
              twiml.Pause();
              twiml.Say("Main Menu");
              twiml.Redirect(url);
          }
          

• 3

  • Twilio processes the TwiML we sent.

• 4

  • Step 2 now repeats until the user is finished using the phone menu. The menu will also exit if the user presses "0" to connect to a receptionist, in which case Twilio will try to connect the caller to the number specified in the <Dial> verb.