Programmable Voice Failover Best Practices
Your communication infrastructure is not monolithic and managed in a single place, but rather a pipeline of decentralized components spanning multiple spheres of ownership and responsibility. There are the PSTNs run by telecom companies. There may be PBXs, SBCs, and VOIP systems that you control. And then there are the solutions from Twilio that bridge those worlds whose technology is run and managed by Twilio. All of those combine together to form the totality of your telecommunications.
You want resiliency end-to-end, which means dealing with failures whether they occur within the parts of the architecture you control or those you don't. At Twilio, we have invested heavily in making sure our infrastructure is robust, with failover strategies in place across the world to ensure consistent service, even in the face of carrier outages.
Inevitably, however, things will occasionally go wrong at any part of the architecture. This document describes steps you can take within your own systems and applications to add resiliency to handle failure scenarios, minimizing loss of functionality.
The following sections are broken up into different functional areas for Twilio Voice. Each one has a list of suggestions you can make to deal with failover. The best practices are all independent of each other, so look at the sections that apply to your Twilio usage, and adopt the suggestions that are relevant to your use cases.
This section contains best practices for SIP trunking termination, outgoing traffic from your communications infrastructure to the PSTN via Twilio.
{yourdomain}.pstn.twilio.com, or a specific geographic edge location nearest to your communications infrastructure, such as {yourdomain}.pstn.sydney.twilio.com. (See the full list of edge locations.)Whichever address you use, resolving the FQDN (Fully Qualified Domain Name) will result in 3-4 IP addresses returned from DNS, spread across multiple availability zones for resiliency.
Do not pin a single IP address, but instead utilize all of the IP addresses, failing over from one to the next when you don't receive a response from one of them, or the response takes too long. Twilio suggest 4 seconds as good starting point for a timeout interval.
For more information, including timeout recommendations, see Redundancy with Termination URIs.
You can configure your SIP infrastructure to connect to a specific Twilio geographic location. Usually you would pick the closest one to your egress point to minimize latency. (See the full list of edge locations.) If your SIP system allows it, configure one or more fallback SIP URIs to other Twilio edge locations. In the event of an outage in your primary edge location, a fallback will be used so that service continues for your users.
For example, you may specify {yourdomain}.pstn.dublin.twilio.com (Europe Ireland) as your primary termination SIP URI, and {yourdomain}.pstn.frankfurt.twilio.com (Europe Germany) as a fallback. If there is a failure in the Dublin region, your connections will go through Frankfurt.
This section contains best practices for SIP trunking origination, incoming traffic to your communications infrastructure from the PSTN via Twilio.
_10curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXX/Messages.json \_10 --data-urlencode "To=+13105555555" \_10 --data-urlencode "From=+12125551234" \_10 --data-urlencode "MediaUrl=https://demo.twilio.com/owl.png" \_10 --data-urlencode "Body=Hello from my Twilio line!" \_10 -u ACXXXXXXXXXX:your_auth_token'
However you can also explicitly specify the edge location you'd like to use with the pattern api.{edge}.us1.twilio.com where {edge} is one of the Twilio edge locations listed in Edge Locations. For example, api.sydney.us1.twilio.com. If you use the generic endpoint api.twilio.com it will default to ashburn.
When using a server-side helper library, you don't provide the domain explicitly, but instead provide the region and edge you'd like to use. Here is a Javascript example:
_10const client = require("twilio")(accountSid, authToken, { edge: "sydney" });_10_10client.messages_10 .create({_10 body: "Hello from my Twilio line!",_10 from: "+12125551234",_10 to: "+13105555555",_10 })_10 .then((message) => console.log(message));
At the time of writing, there are three regions available: us1, ie1 (voice) and au1 (voice). More regions will be coming online in the future. If region is unspecified, then the default us1 is used.
If you don't receive a response from the edge you tried, then you should fallback to your next preferred edge. For instance, if your request to api.ashburn.us1.twilio.com (US East Coast) failed, then your client can try api.umatilla.us1.twilio.com (US West Coast).
This section contains best practices for web and mobile client SDKs.
When making a call, the device can specify the preferred edge to connect to. For reduced latency and increased performance, you will typically use the edge location nearest the SIP device. Examples:
| Javascript: | Twilio.Device.setup(token, { edge: ['dublin'] }); |
| iOS: | TwilioVoice.edge = "dublin"; |
| Android: | Voice.setEdge("dublin"); |
If the edge location you selected is experiencing an outage and the call cannot be established, you can then try your next preferred edge location. You can read more about this at Edge Locations.
The Javascript SDK has additional capability that will enable automatic edge fallback functionality if you specify an array of edge locations: Twilio.Device.setup(token, { edge: ['dublin', 'frankfurt', 'ashburn'] });
That lets you specify the preferred edge to use, along with one or more fallback locations in case the first location fails. In the previous example, the SDK will attempt to connect to dublin. If dublin is unreachable, the attempt will fail, and the SDK will then attempt to connect to frankfurt, and so on. For more information, see the Voice SDK Edge docs.
If the token provider used by your clients is not available, then they will not be able to make and receive calls. Ensure that your token provider has redundancy and failover capabilities.