Migrating your application to a new Region
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.
- Twilio's Region isolation model
- Preparing your application in an alternate Region
- Prepare and configure Regional resources
- Setup the Phone Numbers configuration in the alternate Region
- Migrate your application to an alternate Region
- Adjust your application's connections to Twilio
- Update the phone number's incoming call routing setting
- Test your application and verify migration
- Troubleshooting tips
- Twilio Regions for High Availability
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:
- Any Twilio resources that your application depends on (e.g. API Keys, TwiML Apps, SIP Domains, etc) must be explicitly created in the new Region.
- Any existing Twilio resources that have been generated by your application (Call logs, Recordings, etc) in your original Region will not be present in the new Region.
- Some Twilio products may not be available in the new Region. See the product and feature availability reference page for details.
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:
- Programmable Voice features:
- Incoming call handling
- TwiML instruction processing
IVR Feature: Option to leave a voice message
Twilio Requirements:
- Programmable Voice features:
- Call Recordings
IVR Feature: Option to speak to an agent
Twilio Requirements:
- Programmable Voice features:
- Voice Conference
- REST API access (for managing Call and Conference resources)
IVR Feature: Web-based agent dashboard
Twilio Requirements:
- Voice JS SDK
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.
Warning
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.
Danger
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.
- API Keys
- TwiML Applications
- SIP Domains and associated ACLs
- SIP Trunks and associated ACLs
Phone numbers belonging to your account can be updated to route to any region. This is because they are a part of a special category of Twilio resources that are globally routable. These resources include phone numbers, SIP Domain URIs, and SIP Trunk Termination URIs.
When Twilio receives incoming phone calls or messages to one of these globally routable 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.
Later we will go over how to update the routing configuration of these globally routable resources to route to the target Region, but before we do that, we need to update the resource's configuration in the target Region.
Follow these steps to update the configuration of the phone number in the target Region using the Console.
- If you haven't already, pin the Phone Numbers product menu for your target Region so you can access the region-specific configuration.
- Access your phone number's configuration in the target Region
- Update the configuration with the resource to be called for an incoming call and any fallback URL and status callback URL you wish to use. See the Specify a fallback when making a call section of the Programmable Voice Failover Best Practices guide for best practices on setting fallback URLs.
You can also use the API to access and update the region-specific configuration of a phone number using the IncomingPhoneNumber resource. See Using the Twilio REST API in a non-US Region for how to access the IncomingPhoneNumber resource in the target Region.
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.
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 server-side SDKs) | Specify target Edge and Region in request hostname |
| REST API request (using Twilio server-side SDKs) | Specify target Edge and Region in client constructor region parameter |
| SDK connection | Specify target Region in Access Token |
Warning
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.
Update the Region that handles incoming calls to your phone numbers to the target-Region. You can do this using the Console or the API.
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. 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. | Be sure that your connection is configured for the correct target Region.When using a Twilio server-side SDK 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. | Be sure that your connection is configured for the correct target Region.When using a Twilio server-side SDK 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 steps 1 and 2 of the application migration process described above to prepare your alternate Region, and follow steps 3, 4, and 5 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.