Use the Android Voice SDK with a non-US Twilio Region
Integrating your Twilio Voice Android app 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 explain the changes required in order to use your Android app with a non-US1 Twilio Region. We’ll then walk through the steps of migrating a sample app from the default US1 Region to the IE1 Region. You can follow along by setting up the sample app and following the migration steps yourself, or apply the same steps to your own Twilio Voice Android app.
To get the most out of this guide, make sure you’re familiar with the basics of how to build applications using the Programmable Voice Android SDK first.
How the Android SDK uses Regions
The Twilio Voice Android 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 app to target the Ireland (IE1) Region. For a complete list of available Regions, see our Regional product availability reference.
Access tokens and the target Region
The SDK authenticates with Twilio using an Access Token generated by a backend component of your application. The Access Token encodes information about the app instance, including:
- Twilio Region
- Twilio API credentials
- SDK Client identity and permissions
- TwiML Application SID
- Push Credential SID
The Twilio resources referred to by the Access Token (the API Key, TwiML Application, and Push Credential) must exist in the Twilio Region specified in the Access Token.
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 SDK instance to a different Region by specifying the target Region when generating an access token.
A sample Android Voice app running in US1
This guide uses the Voice Quickstart for Android sample app. Begin by walking through the steps in the Getting Started section to get the sample app up and running using the default US1 Twilio Region.
Note: To keep the moving parts to a minimum, this sample app embeds a static Access Token string directly in the source code rather than fetching one from a server at runtime.
Since we’ll be adjusting the Access Token parameters during this tutorial, you’ll need to rebuild and launch the app each time you generate a new Access Token.
Feel free to use your own app and Access Token server, instead, if you prefer.
When you’re finished with the guide, you should be able to successfully make outbound calls using the app, as well as answer inbound calls from the app.
At this point, calls to and from the app will be processed and stored in the US1 Region, which you can verify by checking Call Logs for the US1 Region in the Twilio Console (or by using the Twilio REST API to list US1 Call Logs).
Next we’ll look at the steps required to switch the app to the IE1 Region.
Migrate the app to another Twilio Region
To connect the app to the IE1 Region, we will update the Region parameter used in its Access Tokens. Additionally, we’ll update the Access Token to refer to Twilio resources which exist in the IE1 Region.
First, we need to create those resources. Follow these steps to create an API Key, TwiML Application, and Push Credential in IE1.
Step 1: Create an API Key in IE1
Visit the Twilio Console to create an API Key in the IE1 Region. Note the SID and the secret values of the new API key.
Step 2: Create a TwiML Application in IE1
Navigate to IE1 -> Voice -> Manage -> TwiML apps and create a new TwiML Application, setting the Voice URL to your TwiML server endpoint. Note the SID of the new TwiML Application.
Step 3: Create a Push Credential in IE1
The Twilio Console interface for managing Push Credentials in Regions other than US1 is not yet available. In the meantime, Push Credentials for other Regions may be managed using the Twilio Notify REST API. Specifically, see the example titled 'Create a Credential resource' in our Notify Credential API docs, and note the parameters specific to the FCM credential type (namely the 'secret' parameter).
Please also note that you'll need to follow the guidance in the docs here about targeting a specific region when using the REST API or Helper Libraries.
Create a Push Credential in the IE1 Region using the REST API, and make a note of the new Credential's SID.
Now that the necessary resources are in place, we can generate a new Access Token that targets the IE1 Region and references the Region-local resources.
Update the function used to generate Access Tokens with the following parameter changes:
|twilioApiKey||<IE1 API Key SID>|
|twilioApiSecret||<IE1 API Key secret>|
|outgoingApplicationSid||<IE1 TwiML Application SID>|
|pushCredentialSid||<IE1 Push Credential SID>|
Generate a new Access Token using the new parameters, and update the Android app's source code with the new value (on line 69 of
Rebuild and launch the application, and test inbound and outbound calling. You can confirm that your calls are being processed in IE1 by reviewing the IE1 Call Logs in Twilio Console or via the REST API.
Now that you know how to connect to a specific Twilio Region using the Android Voice SDK, check out these resources to learn more about building with Twilio’s Global Infrastructure.
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.