Introduction to TwiML

We’ve successfully made a phone ring, but how do we actually control call flow? TwiML is the answer. TwiML is a set of instructions you can use to tell Twilio what to do when you receive an incoming call or SMS. TwiML instructions are formatted in XML and are case sensitive.

When someone makes a call or sends an SMS to one of your Twilio numbers, Twilio will look up the URL associated with that phone number and make a request to that URL. Twilio will read TwiML instructions at that URL to determine what to do: record the call, play a message for the caller, prompt the caller to press digits on their keypad, etc.

TwiML is an XML-based language and consists of five basic verbs for Voice calls.

And one basic verb for SMS messaging.

To see how these verbs work, let’s first take a look at the last section. When we called your phone, a robot answered with a “Hello World” message. We now know that TwiML powered that call, so let’s take a look. Open http://twimlets.com/message?Message=Hello+World in your browser.

Notice the TwiML used for this application. This application uses the Say verb and says “Hello World” with a text-to-speech engine. For outgoing calls, we choose the TwiML URL at the time of the call. For incoming calls, we set a TwiML URL that is fetched each time someone calls into your Twilio number.

Twimlbin

TwiML can be hosted anywhere. It can be a static XML document or created dynamically by a web application. To make developing Twilio applications easier, you can host your TwiML on Twimlbin. Applications with Twimlbin will autosave and let you know when there might be potential errors with your TwiML. While we love Twimlbin, we recommend that you host your Twilio production application on your own server.

Let’s rebuild the “Hello World” greeting in Twimlbin.

To create a new bin, go to the Twimlbin homepage and click “Create a new Twimlbin”.

Now let’s write our “Hello World” application with the following code.

<?xml version="1.0" encoding="UTF-8"?>
<Response><Say>Hello World</Say></Response>

Your final application should look like this.

_images/twimlbin.png

Configuring your phone number

Once you’re done building your application, we’ll want to configure your Twilio phone number. By configuring the Twilio phone number, whenever an incoming call is received on this number, Twilio will fetch the TwiML that is located at that URL.

First, we’ll need to copy the “Public” URL of your Twimlbin.

Go to your Twilio numbers page and click on your Twilio phone number. Change the “Voice URL” field to your Twimlbin URL and “Save Changes”

_images/voiceurl.png

Now give your Twilio number a call! You should hear a “Hello World” greeting.

Call Logs & SMS Logs

Now you’re probably thinking:

  • How long did that call last?
  • How much did that call cost?
  • What time was the call made?

All this information and more can be found in your Call Logs.

Let’s head over to your Call Logs by clicking on the Logs tab from your Account Dashboard.

You’ll notice that the call duration is listed as 1. Call duration is rounded up to the nearest minute.

You SMS Messages logs can also be found under the header SMS Messages

Have any questions about your Logs? Ask your TA!

Debugging Errors

Nobody’s perfect. Eventually, something will break and your application won’t work. Instead of hoping this doesn’t happen, let’s make an error occur. Copy and paste the following TwiML into your Twimlbin.

<?xml version="1.0" encoding="UTF-8"?>
<Response>

This TwiML is invalid. We open the Response and never close it.

Call your phone number. Do you hear application recorded message that says “We’re sorry, an application error has occurred”?

Now let’s find out why your application error has occurred. The first place we’ll want to look is the debugger. Navigate to your account dashboard and find your debugger.

_images/debugger.png

Click on the error to see more detail.

The Debugger lets you know where in your application Twilio ran into an error. This page is broken down into three sections.

The Request section provides information on the data Twilio sent to your server.

The Response section lets you know how your server responded to Twilio. Twilio will always expect correctly formatted TwiML as a response. If your application tries to respond to Twilio with anything else, you will likely run into an error.

The Body section shows the content your application returned to Twilio. Here you’ll see the invalid TwiML from your Twimlbin.

Find the error within the response your application sent to Twilio. What should it look like?

Hint: You may also click on the more information link at the top of the page.