Twilio's default data storage and processing Region is located in the United States. With the availability of other Twilio Regions around the world, you can control data residency and optimize your application's performance by selecting and using the Region that is most appropriate for your needs.
This guide will walk through the steps to migrate your existing application to another Twilio Region.
We'll cover the following topics.
Before embarking on your journey with Regional Twilio, it's critical to understand Twilio's Region isolation model. You can learn about this topic by reading our introduction to Twilio Regions, but in short:
Each Twilio Region operates in isolation of all other Regions; any one Region can only access data within that same Region.
This strict isolation of Regions is necessary in order to guarantee availability, performance, and data sovereignty. However, the isolation model also has some important implications to your application's operation in regard to Twilio. In particular, when moving your application from one Twilio Region to another:
The selection of a Twilio Region depends on your individual needs and goals, and will be driven by factors such as minimizing network latency or solving for data sovereignty. Regardless of your motivations, make sure that the target Region meets your application's critical requirements before engaging in a migration.
Let's look at an example.
Suppose you operate a Twilio-powered IVR system that presents a menu of options for callers to select from. The following table lists the features of the system and the corresponding Twilio requirements:
IVR Feature: Present an interactive menu when a customer calls your phone number
Twilio Requirements:
IVR Feature: Option to leave a voice message
Twilio Requirements:
IVR Feature: Option to speak to an agent
Twilio Requirements:
IVR Feature: Web-based agent dashboard
Twilio Requirements:
Based on this list of requirements, we can refer to the Regional product and feature availability guide to verify that the AU1 or IE1 Regions will indeed support our application.
On the other hand, if your application relies on Twilio products and features which aren't yet available in your target Region (e.g. Twilio Functions, TaskRouter, Programmable Video), it may not be viable to migrate your application at this time.
It is possible in some cases for your application to use multiple Twilio Regions at once.
For example, your application could use Voice features in IE1 while using Messaging features in US1. However, if using Twilio products which interact with each other (e.g. using Twilio Flex to coordinate Programmable Voice interactions), those products must be used within a single Region.
Now that you've selected a target Region, it's time to prepare your Twilio resources in the target Region, and then update your system to connect to the new Region.
Any major migration of your application's configuration in a production environment comes with some risk. To avoid negatively impacting your customers or business, make sure the migration procedure works in a test environment first.
Ideally you can start with a test environment which mirrors your production environment as closely as possible, especially in its usage of Twilio. If you don't already have a test environment, you may want to take this opportunity to set one up.
Your application likely depends on some Twilio resources that you've provisioned for your Twilio account. These resources will exist only in your original Region, and must be explicitly created and configured in your new Region.
Following are some examples of Twilio resources that you may need to create in your target Region. Some of these may not apply to your particular use case.
While any phone numbers belonging to your account may be used with any Region, phone numbers do have Region-specific webhook configurations. To configure your phone numbers in the new target Region, click on Active Numbers under the appropriate Region section of the navigation menu, and then select the number you wish to configure.
While it's possible to create resources in different Regions within a single Twilio Account (or Subaccount), we strongly recommend creating a dedicated Account per Region. Using a Region-specific Account makes it easier to manage and monitor your resources, logs, usage, and billing on a per-Region basis.
Now that you've prepared the resources in your Twilio account within your new target Region, you'll need to make some adjustments in order for your application to start processing its Twilio workloads in the new Region.
When your application connects to Twilio, whether via REST API or SDK connections, these requests are processed in the US1 Region by default. To use your new target Region instead, you must explicitly select the target Region for each of these connections.
| Connection type | How to specify target Region |
|---|---|
| REST API request (without Twilio helper libraries) | Specify target Edge and Region in request hostname |
| REST API request (using Twilio helper libraries) | Specify target Edge and Region in client constructor region parameter |
| SDK connection | Specify target Region in Access Token |
Data sent over these connections often include payloads that reference Twilio resources that exist in your account (e.g. API Keys, TwiML Apps, etc). You will need to update your application configuration to reference the specific Twilio resource SIDs which exist in the new target Region (the resources created in the previous step).
If your application mistakenly references Regions which exist in another Region, it will result in "resource not found" errors.
A special category of Twilio resources corresponds to the externally addressable, global identifiers that are used to specify a destination for incoming phone calls or messages to Twilio. This category is known as globally routable resources, and it includes phone numbers, SIP Domain URIs, and SIP Trunk Termination URIs.
When Twilio receives incoming phone calls or messages to one of these globally routable Twilio resources, the incoming connections first arrive at one of our Edge Locations around the world. Next, the Edge forwards the connection to a Twilio Region for processing. The destination Region is selected according to the resource's routing configuration. You can control the routing configuration of each of your globally routable resources in order to select which Region will be used for incoming calls and messages.
To learn how to configure routing for your phone numbers, see this guide to routing incoming calls. The same routing concept applies to SIP Domains and SIP Termination URIs, however SIP Domains and SIP Termination URIs are not created or visible automatically in the new Region when you change the routing from an existing Region to a new Region. You must create SIP Domains and SIP Termination URIs manually in the target Region with the same configuration and then change the routing.
At this point, any incoming calls or messages to your phone numbers or SIP URIs are being processed in the new target Region. Additionally, any API calls or SDK connections made by your application to Twilio are processed in the new Region.
Test that your application functions as expected, and then use the Twilio Console or REST API to verify that your Call Logs and other Twilio resources created during the operation of your application are being created in the correct Region.
There are multiple moving pieces involved in a Regional Twilio migration, and it's easy to miss something. This section will list some of the most common problems we've seen, and how to fix them.
Twilio REST API requests, SDK connections, and some SIP requests require authentication. The Twilio credentials supplied must exist in the same Region where the traffic is being processed.
Thus, two common mistakes can lead to authentication failures due to credentials not existing in the target Region:
| Mistake | Explanation |
|---|---|
| Requests are targeting the wrong Region. | It's easy to miss a step during migration such that your connections are still targeting your original Region, while the credentials used exist only in the new Region. Be sure that your connection is configured for the correct target Region.When using a Twilio helper library to make API requests, you must specify both the region *and the edge* parameter. Otherwise, connections will fall back to the default US1 Region. |
| The credentials used exist in a different Region than the one you are connecting to. | When you update your application to connect to a new Region, be sure to also adjust it to use credentials which exist in the new Region. |
Errors related to resources not being found (e.g. HTTP 404) can indicate that Twilio is looking in the wrong Region for the resource.
This can have one of the following root causes:
| Mistake | Explanation |
|---|---|
| Requests are targeting the wrong Region. | It's easy to miss a step during migration such that your connections are still targeting your original Region, while the credentials used exist only in the new Region. Be sure that your connection is configured for the correct target Region.When using a Twilio helper library to make API requests, you must specify both the region *and the edge* parameter. Otherwise, connections will fall back to the default US1 Region. |
| The resource you are referencing exists in a different Region. | Check the Console (or use the REST API) to confirm that the resource your are referencing indeed exists in the Region where it is being accessed. |
Not all products or features are supported in all Regions, and attempting to use a feature that is not supported in a Region can result in unexpected outcomes. Check your Twilio error logs in the Console or via API in order to check for this scenario.
There may come a day when your application is unable to utilize your primary Twilio Region to carry out its communications workflows. This could happen due to an Internet or network connectivity issue, or due to an outage affecting Twilio's infrastructure in the Region. In either case, you may be able to restore your application's functionality by temporarily failing over your workload to an alternate Twilio Region.
To prepare a disaster recovery plan for this scenario, you can run two Twilio Regions in an "active/passive" configuration - where your primary Region is active, and an alternate Region is pre-configured and ready to failover to, should the need arise.
Follow step 1 of the application migration process described above to prepare your alternate Region, and follow steps 2 and 3 in order to perform a failover. Be sure to test and validate your failover process in a simulated disaster scenario before a real one occurs to ensure that your recovery plan is viable.
In addition to controlling where your Twilio data is processed and stored using Twilio Regions, you can control where your traffic to and from Twilio enters and exits Twilio's network using Edge Locations.