Skip to contentSkip to navigationSkip to topbar
Rate this Page:

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

review-available-features page anchor

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.

ChatSMSWhatsappFacebook Messenger
US1
IE1xxx
AU1xxxx
(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

configure-your-application-to-use-conversations-in-ie1 page anchor

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

use-the-conversations-rest-api-in-ie1 page anchor

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

authentication-and-credentials page anchor

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.

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:


_10
curl -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(link takes you to an external page) 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

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

Add a chat participant to the Conversation

add-a-chat-participant-to-the-conversation page anchor

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:


_10
curl -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:


_10
curl -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

send-messages-via-the-conversation page anchor

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:


_10
curl -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:


_10
curl -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

manage-conversations-in-ie1-using-twilio-console page anchor

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.

step-1-pin-conversations-ie1.

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

use-the-conversations-mobile-or-web-sdk-in-ie1 page anchor

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)

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


Migrate an existing Conversations app to IE1

migrate-an-existing-conversations-app-to-ie1 page anchor

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.

  1. Provision API credentials for IE1
  2. Update API calls to target IE1
  3. Update Access Token generation code to use IE1 API credentials
  4. 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.


Rate this Page: