Use the Conversations API with Twilio Regions

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.

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.

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.

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.

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.

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.

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:

1
curl -X POST \
2
    -u $API_KEY_SID:$API_KEY_SECRET \
3
    https://conversations.dublin.ie1.twilio.com/v1/Conversations \
4
    --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:

1
const accountSid = process.env.ACCOUNT_SID;
2
const apiKeySid = process.env.API_KEY_SID;
3
const apiKeySecret = process.env.API_KEY_SECRET;
4

5
const client = require('twilio')(
6
  apiKeySid,
7
  apiKeySecret, {
8
    accountSid: accountSid,
9
    edge: 'dublin',
10
    region: 'ie1'
11
});
12

13
client.conversations.conversations
14
  .create({
15
    friendlyName: 'Conversations with Twilio Regions'
16
  });

1
using Twilio;
2
using Twilio.Rest.Api.V2010.Account;
3

4
class Program
5
{
6
    static void Main(string[] args)
7
    {
8
        string accountSid = Environment.GetEnvironmentVariable("ACCOUNT_SID");
9
        string apiKeySid = Environment.GetEnvironmentVariable("API_KEY_SID");
10
        string apiKeySecret = Environment.GetEnvironmentVariable("API_KEY_SECRET");
11

12
        TwilioClient.Init(
13
            apiKeySid,
14
            apiKeySecret,
15
            accountSid=accountSid,
16
            edge="dublin",
17
            region="ie1"
18
        );
19

20
        var conversation = ConversationResource.Create(
21
            friendlyName: "Conversation with Twilio Regions"
22
        );
23
    }
24
}

1
<?php
2

3
// Update the path below to your autoload.php,
4
// see https://getcomposer.org/doc/01-basic-usage.md
5
require_once '/path/to/vendor/autoload.php';
6

7
use Twilio\Rest\Client;
8

9
$account_sid = getenv("ACCOUNT_SID");
10
$api_key_sid = getenv("API_KEY_SID");
11
$api_key_secret = getenv("API_KEY_SECRET");
12

13
$twilio = new Client(
14
    $api_key_sid,
15
    $api_key_secret,
16
    $account_sid,
17
    "ie1");
18

19
$twilio -> setEdge("dublin");
20

21
$conversation = $twilio->conversations->v1->conversations
22
                                          ->create([
23
                                                       "friendlyName" => "Conversations with Twilio Regions"
24
                                                   ]
25
                                          );

1
require "twilio-ruby"
2

3
account_sid = ENV["ACCOUNT_SID"]
4
api_key_sid = ENV["API_KEY_SID"]
5
api_key_secret = ENV["API_KEY_SECRET"]
6

7
@client = Twilio::REST::Client.new(
8
    api_key_sid,
9
    api_key_secret,
10
    account_sid
11
)
12

13
@client.edge = "dublin"
14
@client.region = "ie1"
15

16
conversation = @client.conversations
17
                      .v1
18
                      .conversations
19
                      .create(friendly_name: 'Conversations with Twilio Regions')

1
import os
2
from twilio.rest import Client
3

4
account_sid = os.environ['ACCOUNT_SID']
5
api_key_sid = os.environ['API_KEY_SID']
6
api_key_secret = os.environ['API_KEY_SECRET']
7

8
client = Client(
9
    account_sid=account_sid,
10
    username=api_key_sid,
11
    password=api_key_secret,
12
    edge='dublin',
13
    region='ie1'
14
)
15

16
conversation = client.conversations \
17
                     .v1 \
18
                     .conversations \
19
                     .create(friendly_name='Conversations with Twilio Regions')

1
import com.twilio.Twilio;
2
import com.twilio.rest.api.v2010.account.Call;
3
import com.twilio.type.PhoneNumber;
4
import com.twilio.type.Twiml;
5

6
public class Example {
7

8
    public static final String ACCOUNT_SID = System.getenv("ACCOUNT_SID");
9
    public static final String API_KEY_SID = System.getenv("API_KEY_SID");
10
    public static final String API_KEY_SECRET = System.getenv("API_KEY_SECRET");
11

12
    public static void main(String[] args) {
13
        Twilio.init(API_KEY_SID, API_KEY_SECRET, ACCOUNT_SID);
14
        Twilio.setEdge("dublin");
15
        Twilio.setRegion("ie1");
16

17
        Conversation conversation = Conversation.creator()
18
            .setFriendlyName("Conversations with Twilio Regions").create();
19
    }
20
}

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:

1
curl -X POST \
2
 -u $API_KEY_SID:$API_KEY_SECRET \
3
 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Participants \
4
 --data-urlencode "Identity=Bob"

Add the second chat Participant:

1
curl -X POST \
2
 -u $API_KEY_SID:$API_KEY_SECRET \
3
 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Participants \
4
 --data-urlencode "Identity=Alice"

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:

1
curl -X POST \
2
  -u $API_KEY_SID:$API_KEY_SECRET \
3
  https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Messages \
4
  --data-urlencode "Author=Bob" \
5
  --data-urlencode "Body=Ahoy there"

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

1
curl -X POST \
2
 -u $API_KEY_SID:$API_KEY_SECRET \
3
 https://conversations.dublin.ie1.twilio.com/v1/Conversations/CHXXX/Messages  \
4
 --data-urlencode "Author=Alice" \
5
 --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.

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.

Expand image

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.

Expand image

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

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.

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

1
const conversationsClient = await ConversationsClient.create(
2
  accessToken,
3
  { region: "ie1" }
4
);
5

1
let properties = TwilioConversationsClientProperties()
2
Properties.region = "ie1"
3

4
TwilioConversationsClient.conversationsClient(
5
    withToken: accessToken,
6
    properties: properties,
7
    delegate: self
8
) { _, client in
9
    self.client = client
10
}

1
ConversationsClient.Properties props = ConversationsClient.Properties.newBuilder().setRegion("ie1").createProperties();
2

3
ConversationsClient.create(context, token, props, conversationsClientCallback);

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

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