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

Interactions API



Base URL

base-url page anchor

_10
https://flex-api.twilio.com/v1


The Flex API uses the same HTTP Basic Authentication as other Twilio APIs. Use your Twilio account SID as your username and your Auth Token as your password.



Example Request and Response

example-request-and-response page anchor

The following is an example of an agent-initiated interaction.

Request

request page anchor

Agent-initiated outbound SMS

agent-initiated-outbound-sms page anchor
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({channel: {
_31
type: 'sms',
_31
initiated_by: 'agent',
_31
participants: [
_31
{
_31
address: '+13115552368',
_31
proxy_address: '+192555512345'
_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
.then(interaction => console.log(interaction.sid));

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
}


_38
{
_38
"url": "https://https://flex-api.twilio.com//v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"routing": {
_38
"reservation": null,
_38
"properties": {
_38
"date_updated": 1637013849,
_38
"task_queue_entered_date": 1637013849,
_38
"workflow_name": "Assign to Anyone",
_38
"age_in_queue": 0,
_38
"task_channel_unique_name": "sms",
_38
"assignment_status": "pending",
_38
"queue_name": "Everyone",
_38
"assignmentCounter": 0,
_38
"priority": 0,
_38
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"reason": null,
_38
"attributes": "{\"customerAddress\":\"+1311-555-2368\",\"flexChannelInviteSid\":\"KGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"conversationSid\":\"CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"channelType\":\"sms\",\"conversations\":{\"initiated_by\":\"Agent\",\"communication_channel\":\"Sms\",\"media\":[{\"conversation_sid\":\"CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}],\"direction\":\"Outbound\"},\"customerName\":\"silly name\",\"flexInteractionChannelSid\":\"UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"initiatedBy\":\"agent\",\"direction\":\"outbound\"}",
_38
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"age": 0,
_38
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"timeout": 86400,
_38
"date_created": 1637013849,
_38
"addons": "{}",
_38
"queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_38
}
_38
},
_38
"channel": {
_38
"type": "sms",
_38
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_38
},
_38
"sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"links": {
_38
"channels": "https://https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
_38
}
_38
}


The following table lists a set of "well known" attributes that are consumed by the Flex UI and/or Flex Insights.

AttributeDescriptionExample
customerNameFor Insights, it is used to populate conversations.customers.name.

In the Flex UI, it is rendered as the main customer's name for an email task.
Al Fresco
customerAddressFor Insights, it is used to populate conversations.customers.email or conversations.customers.phone.

In the Flex UI, it is rendered as the main customer's email address for an email task.
+192522212345 or

alfresco@aol.com
fromThis is the Flex UI's preferred attribute for identifying the customer on non-email tasks. For email tasks, it uses customerName.Al Fresco, +19251235555
subjectIn the Flex UI, it is rendered as the initial subject of an email thread task.Issue with shoes
flexInteractionChannelSidUsed in the Flex UI to identify whether a task is interaction-based or not and therefore whether there is a need for Flex UI orchestration or not.UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
flexInteractionSidThe interaction SIDKDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
flexChannelInviteSidThe invite SIDKGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
followed_byUsed for external warm transfers
outcomeUsed for external warm transfers
customersThis object is automatically added if customerAddress and customerName are provided.

This object contains the name, phone, and email of a single customer.

name [required]: The display name of the customer. If name is not available, it must be set to null

phone [required]: The phone number or WhatsApp number of the customer. If number is not available, it should be set to null

email [required]: The email address of the customer. If no email address is available, it should be set to null
"customers": {

"name": "Al Fresco",

"Phone": "+19252148887",

"email": null

}

The following attributes are added when the channel is created (asynchronously):

AttributeDescriptionExample
conversations.external_contact

(This is the Conversation projected address)
For Insights, this is the contact address the customer used to reach you or the contact address from which you have reached them. This may be an inbound support phone number, your support email, or a phone number that appears on the customer's phone when you call them.

The contact information (email, phone) that the customer uses or sees when communicating with the contact center can be used for traffic segmentation.
help@example.com

Task Attributes mapped from Channel Attributes

task-attributes-mapped-from-channel-attributes page anchor

Some interaction request channel attributes are also used to create other task attributes. The following table lists those task attributes that are created from the given channel attributes:

Interaction Channel AttributeTask Attribute(s)Values
typeconversations.media.type (Insights)

For all conversation media types
ChatTranscript
conversations.communication_channel (Insights)Email, SMS, Whatsapp, Web, Chat
channelType (FlexUI)

The Flex UI uses this to identify tasks that have the same "uniqueTaskChannelName" as chat, but have to be treated differently, e.g. whatsapp, sms.
email, sms, whatsapp, web, chat, messenger, gbm
initiated_bydirection (Flex UI)

When initiated_by is set to "agent", this value is outbound, otherwise it's inbound.
customer | api | agent
properties.media_channel_sidconversations.conversation_id (Insights)KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
conversations.media.sid (Insights)
conversationSid (Flex UI)

The following table captures the reason for requiring these attributes:

Flex Insights attributesHow/why is it used
conversations.media.typeExample of the entire media object with attached chat transcript
conversations.initiated_byFlex Insights: Used to identify how the conversation was initiated. This helps to identify funnels leading towards a conversation.
conversations.external_contactFlex Insights: The contact address the customer used to reach you or the contact address from which you have reached them. This may be an inbound support phone number, your support email, or a phone number that appears on the customer's phone when you call them.

Useful for segmenting traffic by contact information (email, phone)
conversations.conversation_id

conversations.media.sid
The ID of the conversation used for Historical insights. The Media SID is used to get access to the transcripts.

Some common errors you may encounter include Error 20003 and Error 11200. See the Twilio Error and Warning Dictionary for a list of potential errors.


Rate this page: