Integrating your Twilio Voice iOS 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 show you how to explicitly select the target Region for your app.
Note: some features required for your iOS app to receive incoming calls while connected to non-US1 Twilio Regions are not yet publicly available. If you are part of our private AU1 Voice Pilot, you can work with your Twilio contacts to set up Push Credentials in AU1 and acquire a pre-release version of the SDK.
This guide will explain the changes required in order to use your iOS 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 AU1 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 iOS 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 iOS SDK first.
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 Australia (AU1) Region. For a complete list of available Regions, see our Regional product availability reference.
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.
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 AU1 Region.
To connect the app to the AU1 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 AU1 Region.
First, we need to create those resources. Follow these steps to create an API Key, TwiML Application, and Push Credential in AU1.
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.
Navigate to AU1 -> 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.
An interface for managing Push Credentials in Regions other than US1 is not yet available. In the meantime, we’ll be working directly with Pilot customers to provision Push Credentials in AU1 as needed.
Arrange for a Twilio employee to create a Push Credential on your behalf, and note the SID of the new Credential.
Now that the necessary resources are in place, we can generate a new Access Token that targets the AU1 Region and references the Region-local resources.
Update the function used to generate Access Tokens with the following parameter changes:
|twilioApiKey||<AU1 API Key SID>|
|twilioApiSecret||<AU1 API Key secret>|
|outgoingApplicationSid||<AU1 TwiML Application SID>|
|pushCredentialSid||<AU1 Push Credential SID>|
Generate a new Access Token using the new parameters, and update the iOS app's source code with the new value (on line 16 of
Finally, acquire and manually install a copy of the 6.4.0-rc1 version of the iOS Voice SDK from a Twilio employee (older SDK versions won’t successfully register for Voip push notifications in non-US1 Regions).
Rebuild and launch the application, and test inbound and outbound calling. You can confirm that your calls are being processed in AU1 by reviewing the AU1 Call Logs in Twilio Console or via the REST API.
Now that you know how to connect to a specific Twilio Region using the iOS Voice SDK, check out these resources to learn more about building with Twilio’s Global Infrastructure.