Menu

Expand
Rate this page:

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
  • Selecting a new Region for your application
  • Migrating your application
    • 1. Prepare Regional resources
    • 2. Adjust your application’s connections to Twilio
    • 3. Configure global resource routing
    • 4. Test your application and verify migration
  • Troubleshooting tips

Twilio's Region isolation model

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.

Selecting a new Region

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

Twilio Requirements

Present an interactive menu when a customer calls your phone number

  • Programmable Voice features:
    • Incoming call handling
    • TwiML instruction processing

Option to leave a voice message

  • Programmable Voice features:
    • Call Recordings

Option to speak to an agent

  • Programmable Voice features:
    • Voice Conference
  • REST API access (for managing Call and Conference resources)

Web-based agent dashboard

  • 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.

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.

Migrating your application

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.

Step 1. Prepare and configure Regional Twilio resources

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

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.

Step 2. Adjust your application’s connections to Twilio

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.

Step 3. Configure Global Resource Routing

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 concepts and UI pattern applies to SIP Domains, and SIP Termination URIs.

Step 4. Test your application and verify your migration

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.

Troubleshooting tips

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.

Authentication failure

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.

Missing resources

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.

Unsupported features

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.

Twilio Regions and Disaster Recovery

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.

Next steps

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.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif