Integrating your browser-based Twilio Voice application with a Twilio Region other than the default United States (US1) Region can provide lower latency and improved control over data residency. This guide will show you how to explicitly select the target Region for your application.
At a high level, the steps we will walk through are:
- Run a sample application using the default US1 Region
- Update the application to process calls in the Australia (AU1) Region by changing the Region parameter and API Key used for its Access Tokens and creating a new TwiML Application in the new Region
- Verify that the application’s calls are being processed in the new Region
Call data is processed and stored in the specific Region that the SDK connects to.
Connecting to the default US1 Region has the following implications for your application:
- Call records (along with any related recordings, etc) will be stored in US1
- Signalling traffic for calls will be sent to/from US1 for processing
- The application can only make or receive calls to/from other SDK instances that are also connected to the US1 Region
- The application can only receive PSTN or SIP Trunking Calls that are also processed in the US1 Region
In this guide we will update our application to target the Australia (AU1) Region. For a complete list of available Regions, see our Regional product availability reference.
The SDK uses
Twilio.Device instances to represent softphone endpoints that can make and receive calls using Twilio.
Twilio.Device instances authenticate with Twilio using an Access Token generated by a backend component in your application. The Access Token encodes information about the
Twilio.Device instance’s Twilio credentials, identity, permissions, and target Region.
If your application doesn’t specify a target Region when generating an Access Token, then the Access Token will target the default US1 Region.
In the next sections we’ll look at how to connect your
Twilio.Device instances to a different Region by specifying the target Region when generating access tokens.
The sample application includes two major components:
- Fetches an Access Token from the backend
- Uses a
Twilio.Deviceinstance to make and receive calls
- A backend server application written in Python
- Serves static content that makes up the frontend application
- Provides an endpoint for vending Twilio SDK Access Tokens to the frontend
- Provides an endpoint for serving TwiML responses for Twilio webhook requests
While the examples in this guide assume a backend implemented in Python, the concepts covered apply to any Voice JS SDK application, regardless of which language is used to implement the backend server component.
We’ll start by setting up the application as-is, without explicitly specifying a target Region. The application's
Twilio.Device instances will connect to the default US1 Region.
Begin by cloning the repository and following the Setup and Local Development instructions included in the Readme.
IMPORTANT: When you download the JS SDK, be sure to use version 2.1.0-rc1 or later. Earlier versions do not support using non-US Regions.
Follow the Readme instructions to test inbound and outbound calling with your application.
Now, navigate to the Twilio Console Call Logs page for the US1 Region, and find the call logs for the test calls you just made. Then navigate to the Call Logs page for the AU1 Region, and note that the logs do not appear there, since call data is isolated to the Region where the call was processed. Review the introduction to Twilio Regions for a refresher on Twilio’s Region isolation model.
Now that you have a working application that’s using the default Twilio Region of US1, let’s look at the steps we need to take in order to migrate the application’s call processing to a different Twilio Region.
To cause our
Twilio.Device instances to process calls in the AU1 Region, we must update our code to specify the Region parameter in the Access Tokens that our backend component generates. Additionally, we need to make sure that the API Key included in the Access Token is an API Key that exists in the AU1 Region.
Follow these steps to make the changes:
Visit the Twilio Console to create an API Key in the AU1 Region. Note the SID and the secret values of the new API key.
.env file in the application directory to use the new API Key’s SID and secret values.
Change the token generation portion of the code on line 44 of
app.py to include the
token = AccessToken( account_sid, api_key, api_secret, identity=identity, region='au1' )
After making the changes, restart the application, refresh your browser tabs, and initiate another browser-to-browser call between the two tabs.
Twilio.Device instances will connect to the AU1 Twilio Region for call processing, and the corresponding Call logs will be created and stored in the AU1 Region. Verify this by visiting the AU1 Call Logs page in the Console to see the new call logs.
Pin the Programmable communications > Voice product menu for your target Region (Example: Pin the Phone Numbers product menu for your target Region).
Create a new TwiML Application. You will also need to configure the Voice "REQUEST URL" on the TwiML app once you've got your server up and running.