On this pageProducts used

Use the Conversations API with Twilio Regions

The chat channel for Twilio Conversations is now available in our new Ireland (IE1) Region . Use the IE1 Region if you would like your application's chat data to be processed and stored in our Ireland data centers.

This guide will walk you through the changes you'll need to make to your application in order to use the IE1 Region.

If you're new to Twilio Conversations, please take a look at overview page and complete the Conversations API Quickstart before reading this guide. It's also helpful to be familiar with the fundamental concepts introduced in our guide to understanding Twilio Regions.

Review Available Features

Before we get started, it's important to review the list of available Conversations channels and features, to make sure that your use case is supported in your target Twilio Region.

The following table shows the available channels per Region.

	Chat	SMS	WhatsApp	Facebook Messenger
US1	✅	✅	✅	✅
IE1	✅	x	x	x
AU1	x	x	x	x

(warning)

Warning

Note the following Conversations features are currently unavailable in the IE1 region:

Messaging services
Notification logs
Delivery receipts
Static IP address configuration

If your use case requires a channel or feature that isn't yet available in the IE1 or AU1 Regions, you'll need to use the US1 Region for now.

For a complete list of available Regions and Features, see the availability reference page.

Configure your application to use Conversations in IE1

At a high level, there are two main changes to an application required for it to use Conversations in IE1:

Update the application's API calls to target IE1
Update the application's SDK clients to target to IE1

We'll take a step-by-step look at both in the following sections.

Use the Conversations REST API in IE1

The Twilio Rest API operates on a per-Region basis. To control which Twilio Region is used for your conversations, you can specify a target Region for your API requests and SDK connections.

(warning)

Warning

If you don't specify a target Region in the request, the request will be handled in the default US1 region.

To specify the target Region for an API request, include the name of the target Region and preferred Edge Location in the hostname of the request.

(information)

Info

The target Region specifies the data center where your Conversations data will be processed and stored, while the Edge Location specifies the point where your servers or clients will connect to Twilio's networking infrastructure.

This walkthrough will use the target Region of IE1 with the dublin Edge Location, though you may select to use any of Twilio's public Edge Locations based on the location of your application hosting infrastructure.

The following base URL for the Conversations API encodes these selections in the hostname:

https://conversations.dublin.ie1.twilio.com/v1

If you are using one of Twilio's server-side helper libraries to make API requests, you don't need to worry about constructing the hostname for your requests. Instead, you'll supply the client constructor with edge and region parameters, and the client will automatically construct the appropriate hostname accordingly.

See the examples below, or check out our guide on using the REST API with non-US1 Regions for more details.

Authentication and credentials

Since each Twilio Region operates independently of other Regions, even API credentials such as API Keys are a Region-specific resource. This means that in order to authenticate your API requests against the IE1 Region, the requests need to use an API key that was created specifically for the IE1 region.

Create an API Key in IE1 by following the instructions inour guide to managing Regional API credentials.

Be sure to make a note of the API Key's SID and Secret . You will need this information for the next step.

Create a Conversation

To create your first Conversation with Twilio Regions, you'll need to make a POST request to the Conversation endpoint. You can run the following command:


_10curl -X POST \
_10    -u $API_KEY_SID:$API_KEY_SECRET \
_10    https://conversations.dublin.ie1.twilio.com/v1/Conversations \
_10    --data-urlencode "FriendlyName=Conversations with Twilio Regions"

The response should be a JSON representation of the new Conversation. Note your conversation SID as you will need it for the following steps. You can optionally use any of Twilio's language-specific server-side helper libraries to make the API requests. For example, you can create a Conversation using the Node.js helper library, by passing the region attribute on the client instance, like this:

Node.jsC#PHPRubyPythonJava


_16const accountSid = process.env.ACCOUNT_SID;
_16const apiKeySid = process.env.API_KEY_SID;
_16const apiKeySecret = process.env.API_KEY_SECRET;
_16
_16const client = require('twilio')(
_16  apiKeySid,
_16  apiKeySecret, {
_16    accountSid: accountSid,
_16    edge: 'dublin',
_16    region: 'ie1'
_16});
_16
_16client.conversations.conversations
_16  .create({
_16    friendlyName: 'Conversations with Twilio Regions'
_16  });


_24using Twilio;
_24using Twilio.Rest.Api.V2010.Account;
_24
_24class Program
_24{
_24    static void Main(string[] args)
_24    {
_24        string accountSid = Environment.GetEnvironmentVariable("ACCOUNT_SID");
_24        string apiKeySid = Environment.GetEnvironmentVariable("API_KEY_SID");
_24        string apiKeySecret = Environment.GetEnvironmentVariable("API_KEY_SECRET");
_24
_24        TwilioClient.Init(
_24            apiKeySid,
_24            apiKeySecret,
_24            accountSid=accountSid,
_24            edge="dublin",
_24            region="ie1"
_24        );
_24
_24        var conversation = ConversationResource.Create(
_24            friendlyName: "Conversation with Twilio Regions"
_24        );
_24    }
_24}


_25<?php
_25
_25// Update the path below to your autoload.php,
_25// see https://getcomposer.org/doc/01-basic-usage.md
_25require_once '/path/to/vendor/autoload.php';
_25
_25use Twilio\Rest\Client;
_25
_25$account_sid = getenv("ACCOUNT_SID");
_25$api_key_sid = getenv("API_KEY_SID");
_25$api_key_secret = getenv("API_KEY_SECRET");
_25
_25$twilio = new Client(
_25    $api_key_sid,
_25    $api_key_secret,
_25    $account_sid,
_25    "ie1");
_25
_25$twilio -> setEdge("dublin");
_25
_25$conversation = $twilio->conversations->v1->conversations
_25                                          ->create([
_25                                                       "friendlyName" => "Conversations with Twilio Regions"
_25                                                   ]
_25                                          );


_19require "twilio-ruby"
_19
_19account_sid = ENV["ACCOUNT_SID"]
_19api_key_sid = ENV["API_KEY_SID"]
_19api_key_secret = ENV["API_KEY_SECRET"]
_19
_19@client = Twilio::REST::Client.new(
_19    api_key_sid,
_19    api_key_secret,
_19    account_sid
_19)
_19
_19@client.edge = "dublin"
_19@client.region = "ie1"
_19
_19conversation = @client.conversations
_19                      .v1
_19                      .conversations
_19                      .create(friendly_name: 'Conversations with Twilio Regions')


_19import os
_19from twilio.rest import Client
_19
_19account_sid = os.environ['ACCOUNT_SID']
_19api_key_sid = os.environ['API_KEY_SID']
_19api_key_secret = os.environ['API_KEY_SECRET']
_19
_19client = Client(
_19    account_sid=account_sid,
_19    username=api_key_sid,
_19    password=api_key_secret,
_19    edge='dublin',
_19    region='ie1'
_19)
_19
_19conversation = client.conversations \
_19                     .v1 \
_19                     .conversations \
_19                     .create(friendly_name='Conversations with Twilio Regions')


_20import com.twilio.Twilio;
_20import com.twilio.rest.api.v2010.account.Call;
_20import com.twilio.type.PhoneNumber;
_20import com.twilio.type.Twiml;
_20
_20public class Example {
_20
_20    public static final String ACCOUNT_SID = System.getenv("ACCOUNT_SID");
_20    public static final String API_KEY_SID = System.getenv("API_KEY_SID");
_20    public static final String API_KEY_SECRET = System.getenv("API_KEY_SECRET");
_20
_20    public static void main(String[] args) {
_20        Twilio.init(API_KEY_SID, API_KEY_SECRET, ACCOUNT_SID);
_20        Twilio.setEdge("dublin");
_20        Twilio.setRegion("ie1");
_20
_20        Conversation conversation = Conversation.creator()
_20            .setFriendlyName("Conversations with Twilio Regions").create();
_20    }
_20}

Add a chat participant to the Conversation

Now that we created a Conversation, you can add chat-based Conversations Participants. To have an interactive Conversation, let's add two chat Participants.

Make sure to replace CHXXX with your Conversation SID for the Conversation you created in the step above.

Add the first chat Participant:


_10curl -X POST \
_10 -u $API_KEY_SID:$API_KEY_SECRET \
_10 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Participants \
_10 --data-urlencode "Identity=Bob"

Add the second chat Participant:


_10curl -X POST \
_10 -u $API_KEY_SID:$API_KEY_SECRET \
_10 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Participants \
_10 --data-urlencode "Identity=Alice"

Send Messages via the Conversation

To send the first Message in the Conversation, you can make a POST request to the Conversation Message resource endpoint to create a new Message.

You can run the following command:


_10curl -X POST \
_10  -u $API_KEY_SID:$API_KEY_SECRET \
_10  https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Messages \
_10  --data-urlencode "Author=Bob" \
_10  --data-urlencode "Body=Ahoy there"

Now, you can have the second chat Participant answer to the message:


_10curl -X POST \
_10 -u $API_KEY_SID:$API_KEY_SECRET \
_10 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Messages  \
_10 --data-urlencode "Author=Alice" \
_10 --data-urlencode "Body=Hi,how are you?"

At this point, you've successfully created a Conversation with two chat Participants using a non-US1 Twilio Region. The Conversation record and its related data (Participants, Messages) will only exist in the IE1 Region and will not be accessible in any other Twilio Regions.

Manage Conversations in IE1 using Twilio Console

To manage your IE1-based Conversations resources in the Twilio Console, you'll first need to "pin" the Conversations product to the navigation menu for IE1.

Click the Explore Products link at the bottom of the left-hand navigation menu. Find Conversations in the product list under the Programmable Communications section, and click the arrow symbol next to the pin icon. Now click on Ireland (IE1) to pin the product for that Region.

You will now find an expandable section of the left-hand navigation menu labeled Ireland (IE1) . Selecting items from this section of the menu will show the resources specific to the IE1 Region.

Navigate to Ireland (IE1) -> Conversations -> Manage -> Services and click on the Default Conversations Service link to find the Conversations you created in IE1 during the previous steps.

step-2-navigate-to-conversations-in-ie1.

See this guide to learn more about managing IE1-based resources in Twilio Console.

Use the Conversations mobile or web SDK in IE1

In order to seamlessly interact with Twilio Conversations via the chat channel from mobile or web applications, you'll use one of the Conversations mobile or web SDKs.

SDK clients connect to the US1 Region by default. To connect a client to the IE1 Region instead, you can supply a region parameter to the client constructor.

(warning)

Warning

When an SDK client connects to a given Region, it authenticates using the API credentials that are encoded in the JWT Access Token. The credentials used in the token must exist in the same Region that the client is connecting to, otherwise an authentication failure will occur.

The following examples show how to supply the region parameter for each SDK.

JavascriptiOS (Swift)Android (Java)


_10const conversationsClient = await ConversationsClient.create(
_10  accessToken,
_10  { region: "ie1" }
_10);


_10let properties = TwilioConversationsClientProperties()
_10Properties.region = "ie1"
_10
_10TwilioConversationsClient.conversationsClient(
_10    withToken: accessToken,
_10    properties: properties,
_10    delegate: self
_10) { _, client in
_10    self.client = client
_10}


_10ConversationsClient.Properties props = ConversationsClient.Properties.newBuilder().setRegion("ie1").createProperties();
_10
_10ConversationsClient.create(context, token, props, conversationsClientCallback);

Migrate an existing Conversations app to IE1

Now that you know the basics of using Conversations with the Twilio IE1 Region, you're ready to migrate your own applications.

(warning)

Warning

Twilio cannot migrate your application to another Region on your behalf. Instead, you need to make some adjustments to your application's configuration in order to change the Twilio Region that it integrates with.

If you have a Conversations-powered app up and running already using Twilio's original US1 Region, you can follow these steps to migrate the application to the IE1 Region.

Provision API credentials for IE1
Update API calls to target IE1
Update Access Token generation code to use IE1 API credentials
Update SDK client constructor to connect to IE1

(warning)

Warning

Note that your application will no longer have access to any existing Conversations resources (e.g. Messages, Participants, etc) that had been previously created in US1.