Archive for December, 2011

Callin’ Oates….how we did it

As Michael Selvidge and I were creating Callin’ Oates a few weeks go, I wanted to jot down my experiences with the Twilio APIs and create a simple guide to follow for newbies. Given the state of my ridiculously lame PHP skills, if I can do it, almost anybody can do it (with a little help). This first post will be the basic framework for our app. If you are remotely familar with Twilio and basic coding, go nuts here. If not, in the coming days and weeks, I will post a few entries on how I started from scratch and the sample apps I built (and am building) along the way.

Michael had a good idea for creating a phone number that people could dial into and select what they wanted to hear. We knew that Twilio’s platform would allow us to build it quickly and easily. Here’s how we did it.

We knew that we needed what’s called an “IVR” (Intearactive Voice Response) so we started by reading up on the IVR the Basics from Twilio’s How To Guides. We then realized we would need to split the application into two parts. If you read over the IVR the Basics post from Twilio, you will see how close the Callin’ Oates code below actually is. The first is the file used to greet the caller and present the audio options. After a little trial and error, here is the properly formatted file that we created (based on TwiML):


<?xml version="1.0" encoding="UTF-8"?>
 <Gather action="handle-user-input.php" numDigits="1">
 <Say voice="woman" language="en">This is your welcome message to the users</Say>
 <Say voice="woman" language="en">To hear the first option, please press 1.</Say>
 <Say voice="woman" language="en">To hear the second option, please press 2.</Say>
 <Say voice="woman" language="en">To hear the third option, please press 3.</Say>
 <Say voice="woman" language="en">To hear the fourth option, please press 4.</Say>
 <!-- If user doesn't input anything, prompt and try again. -->
 <Say>Sorry, I didn't get your response.</Say>

As seen in that file, Twilio’s basic language makes it simple to create the  voice menu for the users. The key to that file is telling the app what to do with the response once the user presses a key on their phone. We need to tell the app where to send the user-entered data and what to do with it, so we created handle-user-input.php.

Next, we turn our focus to the handle-user-input.php. This php script would be the core of our app and respond to the digit pressed by the user and execute accordingly. Replace the bits below to reference the full URL of your own personal audio files that you want to have played based on the user’s selection. We did this with Hall and Oates songs–and they turned out to be really cool about it. No guarantees if you want to make a Metallica phone line (*cough* Napster).


 header('Content-type: text/xml');
 echo '<?xml version="1.0" encoding="UTF-8"?>';

echo '<Response>';

 //Create variable with user input.
 $user_pushed = (int) $_REQUEST['Digits'];

if ($user_pushed == 1)
 echo '<Play>URL OF YOUR FIRST FILE TO PLAY</Play>';
 elseif ($user_pushed == 2)
 elseif ($user_pushed ==3)
 echo '<Play>URL OF YOUR THRD FILE TO PLAY</Play>';
 elseif ($user_pushed ==4)
 echo '<Play>URL OF YOUR FORTH FILE TO PLAY</Play>';

 echo "<Say>Sorry, I can't do that yet.</Say>";
 echo '<Redirect>handle-incoming-call.php</Redirect>';

echo '</Response>';

Once executed, the code above will create a properly formatted response for the Twilio server to process.

With these two files, you can easily create an interactive voice system to do any of the following:

  • Play a song/file based on user selection (as seen above)
  • Change the <Play> verb to <Say> and read a message to the user.
  • Add Twilio credentials to the script and change the <Play> verb to <sms> and send a text message.
  • Add Twilio credentials to the script and change the <Play> verb to <dial> and call another number.

Over the next few days I will start from the beginning of developing with Twilio, including how to setup a simple dev environment,  how to create and publish a simple app, etc….all from the point of view of a person with about as much PHP skills as a blind baboon.