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

Channels Subresource


(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.

The Interactions Channels subresource represents the communication channel associated with the interaction. An interaction channel may have multiple tasks associated with it but can only have one Twilio Conversation associated.

This subresource allows you to update the status of a channel but does not support creating a channel directly. Use the Interactions resource to create a channel.

When a channel is created through the Interactions resource, a task is created and is immediately routed to Flex using the supplied TaskRouter workspace.


InteractionChannel Properties

interactionchannel-properties page anchor
Property nameTypePIIDescription
sidSID<UO>
Not PII

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

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

interaction_sidSID<KD>

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

typeenum<string>

The Interaction Channel's type. Can be: sms, email, chat, whatsapp, web, messenger, or 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

Possible values:
voicesmsemailwebwhatsappchatmessengergbm

statusenum<string>

The status of this channel.

Possible values:
setupactivefailedclosedinactive

error_codeinteger

The Twilio error code for a failed channel.


error_messagestring

The error message for a failed channel.


urlstring<uri>

linksobject<uri-map>
ParameterSub-fieldsDescription
Status [required]Indicates the interaction channel status. When a channel is set to closed, all tasks are put in "wrapping" state by default unless the Routing status is set to "closed" in which case the tasks will be "completed".

Value: closed
Routing [optional]The state of associated tasks. If not specified, all tasks will be set to "wrapping".
statusValue: closed

If closed is specified, all associated tasks will be set to "completed".

GET https://flex-api.twilio.com/v1/Interactions/{InteractionSid}/Channels/{Sid}

This lets you retrieve a single Channel instance.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
InteractionSidSID<KD>required

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

SidSID<UO>required

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

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

Fetch a Channel

fetch-a-channel-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_13
{
_13
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"type": "chat",
_13
"interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"status": "closed",
_13
"error_code": 19025,
_13
"error_message": "Channel validation error",
_13
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
_13
"links": {
_13
"participants": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
_13
"invites": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
_13
}
_13
}



_10
GET /Interactions/<interaction_sid>/Channels

Since only one Channel is supported in the private beta release, only one Channel will be returned.

ParameterDescription
sidUnique identifier for the interaction channel
interaction_sidUnique identifier for the interaction
The channel type specified when the interaction was created. Please refer to the Interactions Properties table for possible values.
linksA JSON object linking to the interaction channel's associated participants and invites
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_13
{
_13
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"type": "chat",
_13
"interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"status": "closed",
_13
"error_code": 19025,
_13
"error_message": "Channel validation error",
_13
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
_13
"links": {
_13
"participants": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
_13
"invites": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
_13
}
_13
}

(information)

Info

An interaction channel (UOXXXXXX) is deleted after 180 days of inactivity, regardless of its state. Retrieving the channel after 180 days from deletion returns a 404 Not Found. Note that the initial TTL (Time to Live) period resets every time there is an update to the interaction channel, such as if an agent accepts the new task through Flex UI. Changes to the Conversations channel, such as updating conversation status or adding or removing a participant, do not reset the interaction channel's inactivity period.


Update an InteractionChannel resource

update-an-interactionchannel-resource page anchor
POST https://flex-api.twilio.com/v1/Interactions/{InteractionSid}/Channels/{Sid}

This subresource lets a developer close a channel in an interaction. When you close a channel, all tasks and reservations for all agents on the channel will be set to wrapup state. If you wish to complete the tasks, you can supply the optional routing status parameter with the value closed.

Furthermore, when you set the channel status to closed, the underlying media channel will also be closed. This changes the channel to "read-only" regardless of the routing status.

The following table illustrates the media channel and task states for a given Channel and Routing status.

Channel statusRouting statusResulting task stateResulting conversation state
closedNot specifiedwrappingclosed
closedclosedcompletedclosed

In some cases, it is desired to keep the channel open but have the agents complete their tasks. To achieve this, use the Channel Participants subresource to modify the status of the participants rather than the channel. Note however that you will need to add more logic to ensure the next incoming message.

Property nameTypeRequiredPIIDescription
InteractionSidSID<KD>required

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

SidSID<UO>required

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

Pattern: ^UO[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
Statusenum<string>required

Required. Indicates the Interaction channel's status. When a channel is set to closed, all tasks are put in the wrapping state by default unless the Routing status is set to closed in which case the tasks will be completed. When a channel is set to inactive, it is mandatory to set the Routing status as closed else the request will be invalid. Value: closed, inactive

Possible values:
closedinactive

RoutingobjectOptional

It changes the state of associated tasks. Routing status is required, When the channel status is set to inactive. Allowed Value for routing status is closed. Otherwise Optional, if not specified, all tasks will be set to wrapping.

Close an interaction channel and wrap agent participants

close-an-interaction-channel-and-wrap-agent-participants page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_12
{
_12
"sid": "UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"channel_sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"type": "agent",
_12
"routing_properties": {
_12
"task_sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"worker_sid": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"reservation_sid": "WRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_12
},
_12
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants/UTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1"
_12
}


Close an Interaction Channel

close-an-interaction-channel page anchor
POST https://flex-api.twilio.com/v1/Interactions/{InteractionSid}/Channels/{Sid}

This subresource lets a developer close a channel in an interaction. When you close a channel, all tasks and reservations for all agents on the channel will be set to wrapup state. If you wish to complete the tasks, you can supply the optional routing status parameter with the value closed.

Furthermore, when you set the channel status to closed, the underlying media channel will also be closed. This changes the channel to "read-only" regardless of the routing status.

The following table illustrates the media channel and task states for a given Channel and Routing status.

Channel statusRouting statusResulting task stateResulting conversation state
closedNot specifiedwrappingclosed
closedclosedcompletedclosed

In some cases, it is desired to keep the channel open but have the agents complete their tasks. To achieve this, use the Channel Participant subresource to modify the status of the participants rather than the channel. Note however that you will need to add more logic to ensure you invite the same or a new agent on the next incoming message.

Property nameTypeRequiredPIIDescription
InteractionSidSID<KD>required

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

SidSID<UO>required

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

Pattern: ^UO[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
Statusenum<string>required

Required. Indicates the Interaction channel's status. When a channel is set to closed, all tasks are put in the wrapping state by default unless the Routing status is set to closed in which case the tasks will be completed. When a channel is set to inactive, it is mandatory to set the Routing status as closed else the request will be invalid. Value: closed, inactive

Possible values:
closedinactive

RoutingobjectOptional

It changes the state of associated tasks. Routing status is required, When the channel status is set to inactive. Allowed Value for routing status is closed. Otherwise Optional, if not specified, all tasks will be set to wrapping.

Close an interaction channel and wrap agent participants

close-an-interaction-channel-and-wrap-agent-participants-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_13
{
_13
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"type": "chat",
_13
"status": "closed",
_13
"error_code": 19025,
_13
"error_message": "Channel validation error",
_13
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
_13
"links": {
_13
"participants": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
_13
"invites": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
_13
}
_13
}

Close an interaction channel and complete all tasks

close-an-interaction-channel-and-complete-all-tasks page anchor
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('KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.channels('UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.update({routing: {
_13
status: 'closed'
_13
}, status: 'closed'})
_13
.then(interaction_channel => console.log(interaction_channel.sid));

Output

_13
{
_13
"sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"type": "chat",
_13
"status": "closed",
_13
"error_code": 19025,
_13
"error_message": "Channel validation error",
_13
"url": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
_13
"links": {
_13
"participants": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
_13
"invites": "https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
_13
}
_13
}


Rate this page: