Rate this page:

Use the Voice iOS SDK with a non-US Twilio Region

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.

How the iOS SDK uses Regions

The Twilio Voice iOS 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 Australia (AU1) 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 iOS Voice app running in US1

This guide uses the Voice Quickstart for Swift sample app. Begin by walking through the steps in the Getting Started guide 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 AU1 Region.

Migrate the app to another Twilio 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.

Step 1: Create an API Key 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.

Step 2: Create a TwiML Application in AU1

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.

Step 3: Create a Push Credential in AU1

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:

Parameter New value
region au1
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 ViewController.m).

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.

Next steps

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.

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