A Hidden Gem: Fallback URLs

A Hidden Gem: Fallback URLs

When you build an application with Twilio, connecting your app to your Twilio number is simply a matter of defining a couple of webhooks to the parts of your application that will be handling voice and SMS requests. Just like that, voice and SMS are live. But sometimes you might want a backup set of instructions in case of any issues, like for example, a communication breakdown between Twilio and your web application. You can easily go beyond the initial defaults to configure your application to deal with scenarios like this using a Voice and SMS Fallback URLs.

Twilio applications are, by their nature, distributed applications and the connections are defined by the Voice Request URL and SMS Request URL. If Twilio cannot retrieve a valid response from the webhooks you define, it will respond in a pre-defined way:

• For an error retrieving a Voice Request URL, an error is logged and a pre-recorded message is played back to the caller indicating that an error has occurred.
• For an error retrieving a SMS Request URL, an error is logged and nothing more is done.

An error retrieving your URL can happen for a variety of reasons, two common ones are:

1. The request times out (default timeout is set to 15 seconds)
2. The returned TwiML is invalid

Here is a full list of the possible errors. If your application needs to define different behavior in this scenario, you can define a custom Fallback URL for both Voice and SMS.  You can show these additional fields by clicking on the “Optional Voice Setting” and “Optional SMS Settings” links:

Voice Request Fallback URL

In the event that Twilio can’t reach your Voice Request URL, you can define Voice Fallback URL that Twilio will invoke. Twilio will submit the ‘ErrorCode’ and ‘ErrorUrl’ parameters, indicating the error code of the failure and what URL the failure occurred on.

SMS Request Fallback URL

The SMS Fallback URL works in a similar fashion to the Voice Fallback URL. Twilio will pass you the ‘ErrorCode’ and ‘ErrorURL’ as parameters.

Best Practices for Highly Reliable Apps

Of course being able to specify fallback URLs isn’t helpful if you’re not sure what to do differently during a runtime error of your application. You certainly don’t want to duplicate the request URL in the hope that it will run properly the second time. There are three techniques you can use to help improve the reliability of your application:

1) Keep it simple

If the Request URL you called executes a complicated chain of processing that include multiple potential point of failure, call a Fallback URL that invokes only the minimum required actions and bypasses the most likely points of failure. The simplest possible action would be to return a customized error message and ask the user to try again.

2) Set-up a back-up server

It’s possible that a temporary connectivity issue is causing your Request URL to fail. In this case, it may help to have your Fallback URL hosted on a different server. This server could be as simple as an AWS S3 bucket that contains some static TwiML files. Whatever choice you make for your backup server, availability and reliability should trump functionality.

3) Send a notification

Whether you use voice, SMS, email or some other communication channel, it’s important you someone is notified in the event that a Request URL fails, along with the relevant information (URL and error code). In this way you can continue to debug and improve the availability and reliability of your Twilio applications.