Regional support for Functions and Assets

Functions is a service that lets you run Node.js code without provisioning or managing your own servers, while also providing convenient integrations with the Twilio SDK. Just as Functions lets you host code, Assets allows you to host your static files without needing to think about the underlying infrastructure. With these services, you're free to focus on writing your application, and Twilio will handle the details such as scaling, hosting, and maintenance.

Functions and Assets now support the following Regions:

• US: US1 (GA)
• Ireland: IE1 (Beta)
• Australia: AU1 (Beta)

• Regional isolation : All processing and data storage is specific to your selected Region and cannot be accessed from another Region. This is particularly important if your application data needs to remain within a specific country or region to adhere to data and privacy regulations.
• Minimal latency : If your application is used outside the US, but hosted on the default US Region, requests could take an excessive amount of time as your data travels to the US and back. Selecting a geographically closer Region will give you shorter round-trip latency, and a better experience for customers.

A Service's domain includes its respective Edge and Region. Existing domains that don't include Region and Edge are implicitly set to the US1 Region and Ashburn Edge.

With that in mind, the pattern for Functions URLs with regional support is:

<unique-name>-<random-four-digits>[-<optional-environment-suffix>].<edge>.<region>.twil.io

Examples:

• ahoy-1234.dublin.ie1.twil.io
• owls-3423-stage.sydney.au1.twil.io

If you want to host a Service in multiple Regions, you must deploy individually to each desired Region. There is currently no Console support for deploying a Service to every desired Region. You could, however, write a script that calls the Serverless Toolkit deploy command for each desired Region, or do so with the Serverless API directly depending on the specifics of your use case.

Serverless Functions by default provide your Auth Token as an Environment Variable, accessible via context.AUTH_TOKEN, and use it to initialize the built-in Twilio REST Client which is accessible via context.getTwilioClient(). This Auth Token is specific to the region in which the Function is deployed.

This means that your default Twilio client will only be capable of making requests to Twilio products and services in the same Region. Likewise, your Auth Token will only be valid for interacting with regionalized APIs in the same Region.

In order for your Function to use products that are not available in the same Region, you'll have to break out of regional isolation (which is not recommended unless absolutely necessary). You can do so by manually providing credentials for the alternative Region with support for the service that you wish to interact with.

Protected Functions and Assets use signature validation to protect them from requests that don't originate from Twilio products and services (or your own code that generates secure signatures).

Your application auth token, which is used to generate these signatures, is different from Region to Region. This means that Functions and Assets in one Region may only be triggered by Twilio products in that same Region.

You may also send requests to a Protected Function or Asset in a different Region, but you will need to generate a valid X-Twilio-Signature header based on credentials from that same Region.

1. Go to the Explore page, click the caret on the Functions and Assets card, and select your Region of choice

2. The Console navigation bar will update and show a new section dedicated to the Region that you selected.

   Expand image

   If you expand the newly added Region sub-nav, you will see a new entry for Functions and Assets. When viewing any portion of the Functions and Assets UI for this Region, you'll see a Region indicator along the top of the Console to help you identify which Region you are editing.

   Expand image

3. Create a new Service the same way you would normally with Functions and Assets

4. You'll see that your URL now includes the region you chose

1. Make sure that you have the Twilio CLI and version 3.1.2 or newer of the Serverless Toolkit plugin installed

2. Create a new regional profile:

   Copy code block

   1
   # For example, if you are in the au1 region
   2
   TWILIO_EDGE=sydney twilio login --region=au1
   3
   # For example, if you are in the ie1 region
   4
   TWILIO_EDGE=dublin twilio login --region=ie1

3. Create and develop a new Service if you don't already have one. (If you do, skip to the next step)

4. When deploying your Service with the Serverless Toolkit, specify the profile associated with your intended Region: twilio serverless:deploy -p <YOUR_REGIONAL_PROFILE_NAME>

1
twilio serverless:deploy \
2
  --region=ie1 \
3
  --username=<YOUR_TWILIO_REGIONAL_API_KEY> \
4
  --password=<YOUR_TWILIO_REGIONAL_API_SECRET>

1
twilio-run deploy \
2
  --region=au1 \
3
  --username=<YOUR_TWILIO_REGIONAL_API_KEY> \
4
  --password=<YOUR_TWILIO_REGIONAL_API_SECRET>

To use different environment variables per Region, you can modify your .twilioserverlessrc configuration file by adding your Account SID and respective Region to the projects section that the settings should be applied to. This works with any configurable setting available in .twilioserverlessrc.
For example:

1
{
2
 "projects": {
3
   "AC11111111111111111111111111111111:us1": {
4
     "env": ".env"
5
   },
6
   "AC11111111111111111111111111111111:ie1": {
7
     "env": ".env.ie1"
8
   }
9
 }
10
}

The Serverless API works the same way as other Twilio APIs do across Regions, for example, serverless.twilio.com automatically maps to the US Region and Ashland Edge.

If interacting with the Serverless API in a non-US region, be sure to use the appropriate base URL in your HTTP requests:

• Ireland: serverless.dublin.ie1.twilio.com
• Australia: serverless.sydney.au1.twilio.com

If you're making requests to Twilio in a non-US region with a Twilio Helper Library, you must initialize that SDK's Twilio client with the appropriate values for Region and Edge. This guide goes into detail about how to do so.

The Runtime Handler provides Environment Variables to help determine where a given Function is being executed. You may use these in logs or any other logic:

• context.TWILIO_REGION
• context.TWILIO_EDGE

There are currently no other Edges available other than the default ones for each region. The default Edges for each Region are:

• us1 → ashburn
• ie1 → dublin
• au1 → sydney

As mentioned earlier, Functions by default are only provided with credentials for and access to Twilio APIs in the same Region. This means that if you deploy to IE1, your Twilio client can only communicate with APIs that are also in IE1.

To create a Twilio client that is capable of communicating with Twilio products in a separate Region:

1. Create a new API Key SID/Secret pair in the Console

2. Add the API Key SID and Secret as environment variables to your Service, for example: TWILIO_US1_API_KEY_SID and TWILIO_US1_API_KEY_SECRET

3. In your Function, create a new Twilio client like so:

   Copy code block

   1
   const clientUs1 = new Twilio(
   2
    context.TWILIO_US1_API_KEY_SID,
   3
    context.TWILIO_US1_API_KEY_SECRET,
   4
    {
   5
      region: 'us1',
   6
      edge: 'ashburn',
   7
      accountSid: context.TWILIO_ACCOUNT_SID
   8
   });

4. Use this US-specific client to make calls to Twilio services in the US, despite your Function operating in another Region (such as Ireland or Australia):

   Copy code block

   1
   clientUs1.messages.create({
   2
     from: context.US_PHONE_NUMBER,
   3
     to: 'some other US number',
   4
     body: 'Ahoy from another region!',
   5
   })
   6
   .then((message) => {
   7
     console.log({ callSid: message.sid });
   8
     return callback();
   9
   })
   10
   .catch((error) => {
   11
     console.error(error);
   12
     return callback(error);
   13
   });