Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Interactions Resource


(information)

Info

Flex Conversations requires Flex UI 2.0.x. If you are on Flex UI 1.x.x, refer to the Messaging in Flex pages.


Interactions Resource

interactions-resource page anchor

The Interactions resource lets you create inbound and outbound interactions for different channel types. To create an interaction, you must supply Channel and Routing attributes. The Channel attributes are used to either create or to bind to an underlying media channel such as a conversation. The Routing attributes are used to create a task which is then routed according to your specified workspace and workflow. A successful interaction results in a task reservation being offered to an agent which references the associated media channel.

(information)

Info

Creating an interaction is an asynchronous request for which a 200 response only indicates that the server has accepted the request. You need to use the getter methods to check if the interaction channel was set up successfully. Additionally, the example JSON responses on this page are not representative of the actual API response. See example response on the API overview page.

In this release, an interaction supports a single channel. Refer to the Invites subresource to see how you can create multiple tasks for the same interaction channel to include multiple agents.


_10
POST /Interactions

(warning)

Warning

Remember to handle certain terminal TaskRouter events according to your application's needs, as conversations may stay orphaned with an open state.

See Conversations Best Practices for details.


Property nameTypePIIDescription
sidSID<KD>
Not PII

The unique string created by Twilio to identify an Interaction resource, prefixed with KD.

Pattern: ^KD[0-9a-fA-F]{32}$Min length: 34Max length: 34

channelobject

A JSON object that defines the Interaction’s communication channel and includes details about the channel. See the Outbound SMS and inbound (API-initiated) Channel object examples.


routingobject

A JSON Object representing the routing rules for the Interaction Channel. See Outbound SMS Example for an example Routing object. The Interactions resource uses TaskRouter for all routing functionality. All attributes in the Routing object on your Interaction request body are added “as is” to the task. For a list of known attributes consumed by the Flex UI and/or Flex Insights, see Known Task Attributes.


urlstring<uri>

linksobject<uri-map>

interaction_context_sidSID<HQ>
Pattern: ^HQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

ParameterSub-fieldsDescription
Channel [required]A JSON object that defines the interaction's communication channel and includes details about the channel. See the Outbound Email, Outbound SMS, and inbound (customer-initiated) Channel object examples.
sid [optional]The SID of the Interaction Channel if already generated. This is a unique identifier for the channel.
type [required]The media channel type.

Allowed values: sms, whatsapp, web, chat, email, messenger, and gbm

Note: These can be different from the task channel type specified in the Routing attributes. Task channel type corresponds to channel capacity while this channel type is the actual media type.
initiated_by [required]The actor that created this Interaction.

Allowed values: customer, agent, or api

customer: Indicates that this interaction was initiated by a customer and will always trigger an inbound task. The media_channel_sid, defined in the properties object, is required and the customer participant must already be in that given media_channel_sid.

agent: initiated by an agent's click. Will always trigger an outbound Task for the same agent. This will also create a new Conversation and add the agent to that Conversation.

api: Triggered or initiated by a secondary type of interaction e.g. webform, automation, etc. This will create an inbound Task. If a media_channel_sid is not given, a new one will be created and the given participants in the participants object will be added.
properties [optional]The media channel properties. It is optional if sid is passed. In this release only Twilio Conversations is supported as a media channel.

Depending on the value used in initiated_by and Channel type, there are required values in some cases as follows:

media_channel_sid is required for all channels, when initiated_by is set to the value customer. Note, this must be set to a Twilio Conversation SID which is prefixed by CH. See the SID property on the Conversation Resource.

For email channel with initiated_by set to agent or api, the following are required:

from: email address of contact center team (e.g. support@yourcompany.com). This is set as the projected_address parameter on the Conversation Participant resource.

from_name: name of contact center team (e.g. Twilio Support).
participants [ ] [optional]An array of participants. Required for outbound interactions where initiated_by is set to agent. Otherwise, it's optional. The specified participants will be added to the media channel and to the interaction channel.

The attributes required to specify the participant address depends on the type of address, as follows:

SMS & Whatsapp:

proxy_address: This is the business number which must be a Twilio-verified number e.g +192555512345, whatsapp:+19251235555

address: Actual phone number of the customer

Chat & Web:

identity: The chat identity of the user in Twilio conversations. We recommend following the standard URI specification and avoid the following reserved characters ! * ' ( ) ; : @ & = + $ , / ? % # [ ] for values such as identity and friendly name.

Email: level: the recipient field. Could be to, cc, or bcc

name: customer display name in your Flex application

address: customer email address

For more information, refer to the Twilio Conversations Participant resource.
Routing [optional]A JSON Object representing the routing rules for the Interaction Channel. See Outbound SMS Example for an example Routing object. The Interactions resource uses TaskRouter for all routing functionality. Routing is optional if sid is provided in Channel object, else Routing is required.
properties [required]Fields needed to create a task:

workspace_sid [required] The TaskRouter Workspace SID which starts with WS.

workflow_sid [optional] The Workflow SID prefixed by WW. Optional if there's only one workflow defined otherwise it's mandatory

queue_sid [required for agent-initiated], the Task router Queue SID prefixed by WQ.

worker_sid [required for agent-initiated]

task_channel_sid [optional]

task_channel_unique_name [optional]

attributes [optional] : The task attributes.

priority [optional]: The priority of the task in the queue.

timeout [optional]: The task/reservation timeout interval in seconds.

All attributes in the Routing object on your Interaction request body are added "as is" to the task. For a list of known attributes consumed by the Flex UI and/or Flex Insights, see Known Task Attributes.

Create an Interaction resource

create-an-interaction-resource page anchor
POST https://flex-api.twilio.com/v1/Interactions

Request body parameters

request-body-parameters page anchor
Property nameTypeRequiredPIIDescription
Channelobjectrequired

The Interaction's channel.


RoutingobjectOptional

The Interaction's routing logic.


InteractionContextSidSID<HQ>Optional

The Interaction context sid is used for adding a context lookup sid

Pattern: ^HQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create an Interaction

create-an-interaction page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.flexApi.v1.interaction
_10
.create({channel: {}})
_10
.then(interaction => console.log(interaction.sid));

Output

_63
{
_63
"sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"channel": {
_63
"type": "sms",
_63
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_63
},
_63
"routing": {
_63
"reservation": null,
_63
"properties": {
_63
"date_updated": 1634845217,
_63
"task_queue_entered_date": 1634845217,
_63
"workflow_name": "Default Fifo Workflow",
_63
"age_in_queue": 0,
_63
"task_channel_unique_name": "default",
_63
"assignment_status": "pending",
_63
"queue_name": "Sample Queue",
_63
"assignmentCounter": 0,
_63
"priority": 0,
_63
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"reason": "",
_63
"attributes": {
_63
"customerAddress": "customer phone address",
_63
"flexChannelInviteSid": "KGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"conversationSid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"channelType": "sms",
_63
"customers": {
_63
"phone": "customer phone address",
_63
"name": "customer name"
_63
},
_63
"conversations": {
_63
"initiated_by": "customer",
_63
"conversation_id": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"media": [
_63
{
_63
"type": "ChatTranscript",
_63
"sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_63
}
_63
]
_63
},
_63
"customerName": "customer name",
_63
"flexInteractionChannelSid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"initiatedBy": "customer",
_63
"flexInteractionSid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"direction": "inbound"
_63
},
_63
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"age": 0,
_63
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"timeout": 86400,
_63
"date_created": 1634845217,
_63
"addons": {},
_63
"queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_63
}
_63
},
_63
"interaction_context_sid": null,
_63
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"links": {
_63
"channels": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
_63
}
_63
}


Customer-initiated SMS Contact

customer-initiated-sms-contact page anchor
(information)

Info

For customer-initiated contacts, you must have an existing Conversation SID for the required media_channel_sid.

In this example, we have configured the SMS address in the Console with a webhook integration. As a result, our endpoint will be called when a new conversation is created and a new message (SMS) is added. At this time, we would create the Interaction and the Channel and have it routed to an agent. The diagram illustrates the flow.

customer-initiated sms contact diagram.

Customer-initiated SMS Contact

customer-initiated-sms-contact-1 page anchor

This requires a preexisting Conversation SID.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.flexApi.v1.interaction
_13
.create({channel: {
_13
type: 'sms',
_13
initiated_by: 'customer'
_13
}})
_13
.then(interaction => console.log(interaction.sid));

Output

_63
{
_63
"sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"channel": {
_63
"type": "sms",
_63
"initiated_by": "customer"
_63
},
_63
"routing": {
_63
"reservation": null,
_63
"properties": {
_63
"date_updated": 1634845217,
_63
"task_queue_entered_date": 1634845217,
_63
"workflow_name": "Default Fifo Workflow",
_63
"age_in_queue": 0,
_63
"task_channel_unique_name": "default",
_63
"assignment_status": "pending",
_63
"queue_name": "Sample Queue",
_63
"assignmentCounter": 0,
_63
"priority": 0,
_63
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"reason": "",
_63
"attributes": {
_63
"customerAddress": "customer phone address",
_63
"flexChannelInviteSid": "KGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"conversationSid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"channelType": "sms",
_63
"customers": {
_63
"phone": "customer phone address",
_63
"name": "customer name"
_63
},
_63
"conversations": {
_63
"initiated_by": "customer",
_63
"conversation_id": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"media": [
_63
{
_63
"type": "ChatTranscript",
_63
"sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_63
}
_63
]
_63
},
_63
"customerName": "customer name",
_63
"flexInteractionChannelSid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"initiatedBy": "customer",
_63
"flexInteractionSid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"direction": "inbound"
_63
},
_63
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"age": 0,
_63
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"timeout": 86400,
_63
"date_created": 1634845217,
_63
"addons": {},
_63
"queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_63
}
_63
},
_63
"interaction_context_sid": null,
_63
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_63
"links": {
_63
"channels": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
_63
}
_63
}


Agent-initiated Outbound Interactions

agent-initiated-outbound-interactions page anchor

This example shows how to create an outbound Flex interaction from your backend application. Use the /Interactions endpoint to implement additional opportunities for agents to send an outbound SMS, WhatsApp, Chat, Email (private beta), and Facebook Messenger (public beta).

Some practical examples include a "click-to-sms" or "click-to-email" functionality in your CRM integration.

outbound agent-initiated interaction diagram.

The API response will contain a newly created task SID, which you can use to update the task attributes, retrieve the conversation SID, or do some additional programming as needed. The agent initiating the interaction must be available in the Flex application to start the conversation in the Flex UI.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_31
// Download the helper library from https://www.twilio.com/docs/node/install
_31
// Find your Account SID and Auth Token at twilio.com/console
_31
// and set the environment variables. See http://twil.io/secure
_31
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_31
const authToken = process.env.TWILIO_AUTH_TOKEN;
_31
const client = require('twilio')(accountSid, authToken);
_31
_31
client.flexApi.v1.interaction
_31
.create({routing: {
_31
properties: {
_31
workspace_sid: 'WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_31
workflow_sid: 'WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_31
queue_sid: 'WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_31
worker_sid: 'WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_31
task_channel_unique_name: 'sms',
_31
attributes: {
_31
customerName: 'silly name',
_31
customerAddress: '+13115552368'
_31
}
_31
}
_31
}, channel: {
_31
type: 'sms',
_31
initiated_by: 'agent',
_31
participants: [
_31
{
_31
address: '+13115552368',
_31
proxy_address: '+192555512345'
_31
}
_31
]
_31
}})
_31
.then(interaction => console.log(interaction.routing));

Output

_31
{
_31
"sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"channel": {
_31
"type": "sms",
_31
"initiated_by": "agent",
_31
"participants": [
_31
{
_31
"address": "+13115552368",
_31
"proxy_address": "+192555512345"
_31
}
_31
]
_31
},
_31
"routing": {
_31
"properties": {
_31
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"worker_sid": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"task_channel_unique_name": "sms",
_31
"attributes": {
_31
"customerName": "silly name",
_31
"customerAddress": "+13115552368"
_31
}
_31
}
_31
},
_31
"interaction_context_sid": null,
_31
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_31
"links": {
_31
"channels": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
_31
}
_31
}


You can use the API to prompt an agent through a workflow to message your customer.

These tasks can be prompted by a customer requesting assistance (for example, an "ask for help" form) or through automation (for example, analysis of reviews). Accordingly, you must indicate that the interaction was initiated by the API. An example flow can go like this:

api-initiated contact diagram.
  1. Your customer fills out a web form on your site or application.
  2. Your application logic creates an interaction. The content from the form is used to populate the task attributes, and the Interactions resource creates an inbound task.
  3. The Interactions endpoint will take care of creating the conversation and adding the participant
  4. An agent is assigned the task, accepts the reservation, and writes to the customer to solve their issue.

In the diagram above, step 2 might look something like this:

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_30
// Download the helper library from https://www.twilio.com/docs/node/install
_30
// Find your Account SID and Auth Token at twilio.com/console
_30
// and set the environment variables. See http://twil.io/secure
_30
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_30
const authToken = process.env.TWILIO_AUTH_TOKEN;
_30
const client = require('twilio')(accountSid, authToken);
_30
_30
client.flexApi.v1.interaction
_30
.create({routing: {
_30
properties: {
_30
workspace_sid: 'WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_30
workflow_sid: 'WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_30
task_channel_unique_name: 'sms',
_30
attributes: {
_30
from: 'testname',
_30
customerName: 'testcustomer',
_30
customerAddress: '+13115552368'
_30
}
_30
}
_30
}, channel: {
_30
type: 'sms',
_30
initiated_by: 'api',
_30
participants: [
_30
{
_30
address: '+13115552368',
_30
proxy_address: '+192555512345'
_30
}
_30
]
_30
}})
_30
.then(interaction => console.log(interaction.sid));

Output

_30
{
_30
"sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"channel": {
_30
"type": "sms",
_30
"initiated_by": "api",
_30
"participants": [
_30
{
_30
"address": "+13115552368",
_30
"proxy_address": "+192555512345"
_30
}
_30
]
_30
},
_30
"routing": {
_30
"properties": {
_30
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"task_channel_unique_name": "sms",
_30
"attributes": {
_30
"from": "testname",
_30
"customerName": "testcustomer",
_30
"customerAddress": "+13115552368"
_30
}
_30
}
_30
},
_30
"interaction_context_sid": null,
_30
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"links": {
_30
"channels": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
_30
}
_30
}


Rate this page: