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:
It's recommended that you have a basic understanding of how to build applications using the Programmable Voice Javascript SDK before following this guide.
The Twilio Voice JavaScript SDK connects to a Twilio Region by way of an Edge Location in order to make and receive calls.
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:
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.
This guide uses the Voice JavaScript SDK Quickstart sample application for Python.
The sample application includes two major components:
An HTML/Javascript frontend application that uses the Twilio Voice Javascript SDK
Twilio.Device
instance to make and receive calls
A backend server application written in Python
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.
Edit the .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 region parameter:
_10token = AccessToken(_10 account_sid,_10 api_key,_10 api_secret,_10 identity=identity,_10 region='au1'_10)
After making the changes, restart the application, refresh your browser tabs, and initiate another browser-to-browser call between the two tabs.
The 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.
Now that you know how to connect to a specific Twilio Region using the JavaScript Voice SDK, check out these resources to learn more about building with Twilio's Global Infrastructure.