Menu

Expand
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

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

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.

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.

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 in our 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:

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

const accountSid = process.env.ACCOUNT_SID;
const apiKeySid = process.env.API_KEY_SID;
const apiKeySecret = process.env.API_KEY_SECRET;

const client = require('twilio')(
  apiKeySid,
  apiKeySecret, {
    accountSid: accountSid,
    edge: 'dublin',
    region: 'ie1'
});

client.conversations.conversations
  .create({
    friendlyName: 'Conversations with Twilio Regions'
  });
using Twilio;
using Twilio.Rest.Api.V2010.Account;

class Program
{
    static void Main(string[] args)
    {
        string accountSid = Environment.GetEnvironmentVariable("ACCOUNT_SID");
        string apiKeySid = Environment.GetEnvironmentVariable("API_KEY_SID");
        string apiKeySecret = Environment.GetEnvironmentVariable("API_KEY_SECRET");

        TwilioClient.Init(
            apiKeySid,
            apiKeySecret,
            accountSid=accountSid,
            edge="dublin",
            region="ie1"
        );

        var conversation = ConversationResource.Create(
            friendlyName: "Conversation with Twilio Regions"
        );
    }
}
<?php

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

use Twilio\Rest\Client;

$account_sid = getenv("ACCOUNT_SID");
$api_key_sid = getenv("API_KEY_SID");
$api_key_secret = getenv("API_KEY_SECRET");

$twilio = new Client(
    $api_key_sid,
    $api_key_secret,
    $account_sid,
    "ie1");

$twilio -> setEdge("dublin");

$conversation = $twilio->conversations->v1->conversations
                                          ->create([
                                                       "friendlyName" => "Conversations with Twilio Regions"
                                                   ]
                                          );
require "twilio-ruby"

account_sid = ENV["ACCOUNT_SID"]
api_key_sid = ENV["API_KEY_SID"]
api_key_secret = ENV["API_KEY_SECRET"]

@client = Twilio::REST::Client.new(
    api_key_sid,
    api_key_secret,
    account_sid
)

@client.edge = "dublin"
@client.region = "ie1"

conversation = @client.conversations
                      .v1
                      .conversations
                      .create(friendly_name: 'Conversations with Twilio Regions')
import os
from twilio.rest import Client


account_sid = os.environ['ACCOUNT_SID']
api_key_sid = os.environ['API_KEY_SID']
api_key_secret = os.environ['API_KEY_SECRET']

client = Client(
    account_sid=account_sid,
    username=api_key_sid,
    password=api_key_secret,
    edge='dublin',
    region='ie1'
)

conversation = client.conversations \
                     .v1 \
                     .conversations \
                     .create(friendly_name='Conversations with Twilio Regions')
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;
import com.twilio.type.PhoneNumber;
import com.twilio.type.Twiml;

public class Example {

    public static final String ACCOUNT_SID = System.getenv("ACCOUNT_SID");
    public static final String API_KEY_SID = System.getenv("API_KEY_SID");
    public static final String API_KEY_SECRET = System.getenv("API_KEY_SECRET");

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

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

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:

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

Add the second chat Participant:

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

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

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

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

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

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.

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.

const conversationsClient = await ConversationsClient.create(
  accessToken,
  { region: "ie1" }
);
let properties = TwilioConversationsClientProperties()
Properties.region = "ie1"
 
TwilioConversationsClient.conversationsClient(
    withToken: accessToken,
    properties: properties,
    delegate: self
) { _, client in
    self.client = client
}
ConversationsClient.Properties props = ConversationsClient.Properties.newBuilder().setRegion("ie1").createProperties();
 
ConversationsClient.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.

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

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:

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