Getting started with TwiML

To set the URLs that Twilio will webhook for incoming calls and SMSes, log in to your Twilio account and choose Numbers from the navigation bar on top of the screen, as shown in the following screenshot:

If you haven't already, you'll want to buy a phone number. Twilio makes this really easy. You just click on Buy a number, which is on the right-hand side, choose your country, and then pick a number of your choice.

Most numbers cost just $1 per month, so cost isn't a huge barrier. Many countries' numbers will support both calls and SMSes, but this is not always the case. Twilio will always tell you what capabilities are supported as part of the buying process.

Once you've got your number, head back to the Numbers screen and click on the one you've just bought.

You'll see that this screen is split into two key sections: Voice and Messaging. You can set separate URLs and HTTP methods for each section. If you're working in PHP, you can usually safely use either GET or POST, but some frameworks and languages will have more specific requirements.

If you click on the optional settings using the link on the right-hand side, you will see a few advanced options which we'll cover. We'll do the same with the powerful Configure with Application setting.

Let's write two quick hello world TwiML snippets, in keeping with programming tradition, using PHP. Start by creating a file called call.php as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Hello world. We love you guys in <?php echo $_GET['FromCountry']; ?>.</Say>
</Response>

In the preceding sample, you'll see that this PHP responds with some XML. XML as a language is very similar to HTML, so it'll look familiar. If you haven't encountered it previously, don't worry; you'll get the hang of it over the course of this chapter.

Inside the <Response> block where Twilio looks to find what it should do in response to the incoming call, we use the <Say> verb. The text we put within the <Say> element is what Twilio's text-to-speech engine will speak.

We're already taking advantage of PHP here by looking at some GET data that Twilio provides with the request. In this case, the voice is going to say the name of the country where the caller is located—FromCountry. There are lots of other great things you can do, which we'll cover later.

After the <Say> verb, Twilio will hang up, as it has nothing more to do.

We've now written a handler for incoming calls, so let's also write one for SMSes. We can do something very similar indeed; let's save this as message.php:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message>Hello world. We love you guys in <?php echo $_GET['FromCountry']; ?>.</Message>
</Response>

As you'll see, we do exactly the same thing here except for using the <Message> verb instead of the <Say> verb. This means that we'll text the sender with the message rather than saying it to them over the phone. We'll cover the <Message> verb in more detail later.

You'll now need to upload these PHP files somewhere where they can be accessed by Twilio. You'll probably have some hosting set up, but if you do not, there are a range of great options. I've included a few recommendations in Chapter 8, Online Resources.

Alternatively, you can use a local server; see my tip on using a great tool called ngrok at the end of the chapter for help with this.

Now that we've set up those PHP files, add the URLs of your call.php and message.php files to your Twilio number, and then hit Save.

Let's see the magic happen. Try calling and SMSing your number. First, Twilio webhooks our TwiML URL, letting our code know about the call and asking it what to do. We respond with TwiML such that Twilio speaks out loud our "hello world" message if we're calling in, or SMSes it to us if we've sent in a text. You've now seen the power of TwiML.