Playing with a Monkey

Upon reading the first few quickstart lessons I knew I was gonna enjoy this since Twilio chose to replace the standard and cliché “Hello World” with a more appropriate “Hello Monkey” introduction application.

I figured that exploring the SMS component of the platform might be an easier place to start given the simplistic nature of SMS in general. I wanted to start with a simple script for sending an outbound SMS message to a small list of recipients, so I read over the guide for Sending Text Messages via the Rest API and began writing some code based on the sample in the referenced quickstart. The documentation on that quicktart guide is really easy to follow and worth a read.

Here is what my first script turned out to look like.

sms_send.php


<?php
 require "Services/Twilio.php";

 // set my AccountSid and AuthToken
 $AccountSid = "XXXXXXXXXXXXXXXXXXXXXXXXXX";
 $AuthToken = "XXXXXXXXXXXXXXXXXXXXXXXXXXX";

 // instantiate a new Twilio Rest Client
 $client = new Services_Twilio($AccountSid, $AuthToken);

 // make a list of people I know, indexed by phone number.
 $people = array(
 "+1415XXXXXXX" => "Reid",
 "+1415XXXXXXX" => "Michael",
 );

 foreach ($people as $number => $name) {

 // Send a new outgoing SMS */
 $sms = $client->account->sms_messages->create(
 // the number I'm sending FROM, must be a number associated with my Twilio account (either verified or a purchased number). Go to your account page on Twilio to either purchase a number or verify an existing number.
 "XXX-XXX-XXXX", $number,

 // the body of the SMS message. $name will be the name from the list of people above.
 "Hey $name, I'm just sending you a quick message to try Twilio."
 );

 // Let me know that the message was sent.
 echo "Sent message to $name";
 }
?>

Once that was created, I simply pushed this file (and the associated PHP helper libraries) to our dotcloud account. Once our URL was returned, I launched it via a browser and within a few seconds received our first SMS message. Or, you can run the php code from the terminal on a Mac simply with php sms_send.php

Beyond easy.

In my next post I’ll discuss how I played with merging the Callin’ Oates code such that we could send an SMS message to individuals that called into our phone number. 

Getting Set….

When Michael and I got together to start playing with the Twilio tools and APIs for the first time, I was immediately intrigued by the simplicity of the system and how well Twilio had laid out the guide for beginners. As you could see in my first post, the necessary code is pretty straightforward. However, there was some pre-work that had to be done prior to our first lines of code being written.

Before we could really get started, we had to build out a primitive dev environment to allow us to collaborate on the codebase while experimenting. Here is what we needed:

  1. Dropbox account for sharing files. If you don’t have one, get one.
  2. dotCloud account for deploying the applications. Once you have an account, you will need to install their command line interface (CLI) application. Instructions available here. If you already have access to a server on the web, you might be able to skip this step and use your own.
  3. Twilio account. Free to create and play around with. Go get one…..I’ll wait.
  4. A Twilio phone number to use. Once you get into your Twilio account, go ahead and buy a number. I didn’t worry about the area codes, most cell phones these days are free long distance anyway.
  5. I was most familiar with PHP, so I chose that as the basis for our work. Depending on the language of your choice, you will likely need to download the API libraries from Twilio.

Michael and I are Apple fanboys so all of this development was done on our Macs.

Our first usage of the system was going to simply be for exploration of the platform while learning the nuts and bolts of the TwiML language used to power our future applications. Once our dev environment was created and running we turned to the Twilio docs, specifically their quickstart guides to learn. The first example, Hello Monkey.

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):

handle-incoming-call.xml


<?xml version="1.0" encoding="UTF-8"?>
 <Response>
 <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>
 </Gather>
 <!-- If user doesn't input anything, prompt and try again. -->
 <Say>Sorry, I didn't get your response.</Say>
 <Redirect>handle-incoming-call.xml</Redirect>
 </Response>

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).

handle-user-input.php

</pre>
<?php
 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)
 {
 echo '<Play>URL OF YOUR SECOND FILE TO PLAY</Play>';
 }
 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>';

 }
 else
 {
 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.

Follow

Get every new post delivered to your Inbox.