Menu

Expand
Rate 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
  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

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

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

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

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.

Migrate the application to another Twilio Region

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.

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.

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

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

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.

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.

Next steps

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:

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!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more