Best practices for working with TwiML

We'll discuss some some helpful tips that can be kept in mind when you're working with TwiML to make your application better organized, more easily testable, and more maintainable.

Test locally using ngrok

When you're working with and building a Twilio application, you'll need to test it frequently by making and receiving real calls on the platform, which requires Twilio to be able to access your local web server.

This is often a challenge with the perils of dynamic IP addresses and port forwarding. Fortunately, there's a great free tool called ngrok (https://ngrok.com), which will help you get around this problem.

It'll give you a special URL (for example, http://123abc.ngrok.com), which Twilio can use to reach your application. So, you can enter this on your numbers in your Dashboard in order to receive inbound calls and SMS messages.

ngrok is simple to use, but you'll need to be at least a little comfortable with the command line:

1. To get started, download the app for your platform from http://ngrok.com. It's currently available on Mac OS X, Windows, and Linux.
2. Start your web server. It can be running on port 80, which is the default HTTP port, but many web servers run on non-standard ports such as 8080 or 3000; both are supported.
3. Unzip ngrok, and then copy it to a location from where it is easily accessible. Ideally, it would be in your shell path, but to start with, you could keep it in your Downloads directory or somewhere else which is easy to access.

The next steps will differ somewhat, depending on whether you're on Windows or another platform.

Windows

1. Open a command prompt from the Start menu, and then use cd to navigate to the folder where ngrok is stored; see http://www.wikihow.com/Change-Directories-in-Command-Prompt if you're not sure how to do this.
2. Once you're there, run ngrok followed by the port your web server is running on (for example, ngrok 80 if your server runs on port 80), and then hit Return.

Mac OS X and Linux (and others!)

Open a terminal and use cd to find the directory where the ngrok executable is stored. For help with navigating, see http://www.linfo.org/cd.html.

Once you're there, run ./ngrok, followed by the port your web server is listening on, for instance, ./ngrok 3000 if your web server works on port 3000.

Once you've run ngrok, you'll see a screen that looks a little like this:

Just copy the second Forwarding URL—the one with HTTPS for additional security and you can use it to build a URL to enter in your Twilio dashboard.

For example, if my TwiML was located at /voicemail/record.xml, I'd enter the https://3625ec81.ngrok.com/voicemail/record.xml URL on Twilio in the previous ngrok session. You'll need to keep your ngrok session running for Twilio to be able to access your application, but once you're done, just hit Ctrl + C.

Make your application resilient with a fallback URL

The very nature of hosting an application is that despite your best intentions and efforts, your TwiML will be unavailable from time to time. This might be due to a bug or an electrical outage with your hosting provider.

With something as critical as a phone service, you want to be sure that when this happens, those using your service will see at worst a graceful degradation of the service they receive.

By default, in case of an error, Twilio will speak in its (somewhat robotic) text-to-speech voice:

"An application error has occurred. Goodbye."

However, we want to provide a better experience than this. For example, in the case of a customer support phone system that will usually have complex menus and queuing, we might want to redirect the call to our switchboard if there was downtime. Twilio's fallback URL functionality makes this possible.

A fallback URL will be used by Twilio to fetch TwiML for an inbound call or SMS (and potentially, outbound calls too) if your usual server is unavailable or returns an error. Here, you'd store some default TwiML for use in a worst-case scenario. In the previous example, we might use something like this:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Please wait while we connect you to our switchboard.</Say>
  <Dial>
    <Number>[phone]</Number>
  </Dial>
</Response>

Tip

We can set up monitoring using Twilio's App Monitor Triggers so that we're informed as soon as our servers start experiencing problems. See Chapter 7, Testing, Debugging, and deploying Twilio Apps, for details.

It makes sense to make the fallback TwiML as simple as possible in order to avoid potential points of failure when our application is experiencing problems.

Tip

Naturally, it's of integral importance that you host your fallback TwiML somewhere separate from your main application. I'd recommend Amazon S3 (http://aws.amazon.com/s3/) as a particularly strong bet from an availability point of view.

We can set a fallback URL from the same Numbers page as where we set up our usual Voice and Messaging URLs. To do this, simply click on the Optional Voice Settings or Optional Messaging Settings button as appropriate, and then enter the location of your TwiML in the Fallback URL field. Finally, click on Save.

Use Twilio's applications to manage your TwiML URLs

At the beginning of this chapter, we set up an inbound phone number by editing that number and setting a URL for Twilio to webhook whenever there's an inbound phone call or message.

This is all well and good, but it makes life much harder if we ever want to conduct maintenance on our application. For example, what if you have hundreds of numbers using the same URL, but you then need to change it?

Twilio provides a great solution for this in the form of TwiML apps. The app functionality lets you predefine sets of URLs that you can then assign to different phone numbers.

To create an app, in your Twilio dashboard navigation bar, go to Dev Tools and then go to TwiML Apps in the subnavigation:

From there, click on the red Create TwiML App button. Specify a name, which is how you'll identify your app across Twilio's interface, and then you can set the various request URLs, just as you'd do for an individual phone number. Once you're done, hit Save:

Tip

An app supports all of the same settings as an individual number, so it can even be used with a fallback URL for improved reliability.

Once you've created an app, you can easily assign it to phone numbers. To do this, head to the Numbers page, choose a number, and then click on Configure with Application. You'll then be able to choose the application you've just created from the list.

From now on, your phone number will stay updated as you make changes to the app. If, for example, you change the URL for an incoming SMS on your app, it'll propagate to each phone number it's attached to.