Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Use the Programmable Voice Javascript SDK with a non-US Twilio Region

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:

  1. Run a sample application using the default US1 Region
  2. 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
  3. Verify that the application's calls are being processed in the new Region

It's recommended that you have a basic understanding of how to build applications using the Programmable Voice Javascript SDK before following this guide.

How the Voice JS SDK uses Regions

how-the-voice-js-sdk-uses-regions page anchor

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:

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

Access Tokens and the target Region

access-tokens-and-the-target-region page anchor

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.

A sample browser-based Voice application

a-sample-browser-based-voice-application page anchor

This guide uses the Voice JavaScript SDK Quickstart sample application for Python(link takes you to an external page).

The sample application includes two major components:

  • An HTML/Javascript frontend application that uses the Twilio Voice Javascript SDK

    • Fetches an Access Token from the backend
    • Uses a Twilio.Device instance 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.

Run the application with the default Twilio Region

run-the-application-with-the-default-twilio-region page anchor

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(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page), and find the call logs for the test calls you just made. Then navigate to the Call Logs page for the AU1 Region(link takes you to an external page), 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.

Migrate the application to another Twilio Region

migrate-the-application-to-another-twilio-region page anchor

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:

1. Update the application's configuration to use an AU1-specific API Key

1-update-the-applications-configuration-to-use-an-au1-specific-api-key page anchor

Visit the Twilio Console to create an API Key in the AU1 Region(link takes you to an external page). 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.

2. Update the application code to specify the target Region when creating an Access Token

2-update-the-application-code-to-specify-the-target-region-when-creating-an-access-token page anchor

Change the token generation portion of the code on line 44 of to include the region parameter:

token = AccessToken(

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(link takes you to an external page) page in the Console to see the new call logs.

3. Create new TwiML Application in the target Region

3-create-new-twiml-application-in-the-target-region page anchor

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.

Rate this page: