Manage Conversations SMS Addresses
Info
Flex Conversations requires Flex UI 2.0. If you are on Flex UI 1.x, please refer to Chat and Messaging pages.
Info
This guide requires Flex UI 2.0. If you are on Flex UI 1.x, refer to Handle an SMS contact with Legacy-based Messaging.
Flex uses Addresses to describe how new Conversations are handled and connected to Flex. Conversations Addresses inform the Conversation Service to auto-create a new Conversation for messages that don't belong to an existing Conversation. Once a Conversation is created, all new messages from the same source to the same destination are routed to the newly created Conversation.
The simplest (and the default) way to route incoming SMS messages for a Phone Number into Flex is to:
- Buy a Phone Number
- Create a Conversations Address for the Phone Number via the Flex Console or the API
- Set the Flex integration on the Address to use the Studio Flow you created earlier
Follow these steps to set up a new SMS Address with the aforementioned configuration via the Flex Console.
If you haven't purchased an SMS-enabled Phone Number yet, or would like to configure a new one, navigate to Phone Numbers > Manage > Buy a number.
Under Phone Numbers > Manage > Active numbers, find the number you want to configure and open it.
For correct operation, make sure your Phone Number Messaging is configured as follows (this should also be the default state):
- Make sure no Messaging Service is selected in the dropdown. If there is one configured, remove it. (For advanced configuration with Messaging Service refer here.)
- Make sure the "A message comes in" webhook handler is set to blank (""). The default handler will respond with a default message for every inbound SMS which is not desired.

Phone Number configuration for Flex Conversations
Warning
If you specify a webhook handler for "A message comes in", it will be executed in parallel to executing the auto-creation functionality defined in the Conversation address. This is most probably undesired for production accounts. Unless you have an advanced use case and know what you're doing, we recommend that you leave the webhook handler blank.
To create an Address for your new Phone Number:
-
Navigate to Flex Console > Manage > Messaging. Select the SMS Numbers tab. (Alternatively you can click "+ Create new SMS Address" on the Addresses tab, and search for your Phone Number on the Create Address form).
-
Search for or click "+ Create new SMS Address" in the Status field of your unregistered Phone Number. Previously configured Phone Numbers will have an "Address created" indicator.
-
You can optionally enter a friendly name.
-
Configure the integration to Flex - either by using Studio Flow you created earlier or your own endpoint URL for the webhook. To learn more about configuring Studio Flows, see Configure pre-agent workflow with Studio.
-
Click Submit to save your new Flex SMS Address.
You can create, edit or delete Flex SMS Addresses at any point using the Console.
The Conversations API's Address Configuration Resource allows you to create and manage SMS addresses for your Twilio account. On address creation, you can specify autocreation of a Conversation upon receipt of an inbound message. The following example shows you the programmatic version of our Console example using the Studio flow integration with a retry count. To learn more about the different resource properties, see Address Configuration Resource.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createConfigurationAddress() {11const addressConfiguration =12await client.conversations.v1.addressConfigurations.create({13address: "+13115552368",14"autoCreation.enabled": true,15"autoCreation.studioFlowSid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",16"autoCreation.studioRetryCount": 3,17"autoCreation.type": "studio",18type: "sms",19});2021console.log(addressConfiguration.sid);22}2324createConfigurationAddress();
Response
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"sid": "IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"address": "+13115552368",5"type": "sms",6"friendly_name": "My Test Configuration",7"address_country": "CA",8"auto_creation": {9"enabled": true,10"type": "webhook",11"conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",12"webhook_url": "https://example.com",13"webhook_method": "POST",14"webhook_filters": [15"onParticipantAdded",16"onMessageAdded"17]18},19"date_created": "2016-03-24T21:05:50Z",20"date_updated": "2016-03-24T21:05:50Z",21"url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"22}
For deleting an SMS address via the API, see Delete Address Configuration.
You are now ready to try your SMS channel:
- Go to Flex > Overview and click Launch Flex.
- Log in and change your activity to Active
- From your mobile phone, send an SMS to the number you just configured
- The Flex UI will display a new task which you can accept to view the inbound message

Under the hood, Flex uses Conversations to send the messages back and forth between the end-customer and the agent. If a Conversations Address is created for a Phone Number (with autocreation set to true), that Address's configuration will be used to handle new inbound messages to that Phone Number.
The Phone Number's "A message comes in" handler isn't used when this Phone Number has a Conversations Address where autocreation
is set to true
.