Skip to content Skip to navigation Skip to topbar

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.

Channel Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<UO>Optional

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>Optional

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>Optional

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>Optional

The status of this channel.

Possible values:

setupactivefailedclosedinactive

error_codeintegerOptional

The Twilio error code for a failed channel.

error_messagestringOptional

The error message for a failed channel.

urlstring<uri>Optional

linksobject<uri-map>Optional

Parameter	Sub-fields	Description
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".
	status	Value: closed If closed is specified, all associated tasks will be set to "completed".

Fetch a Channel

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

This lets you retrieve a single Channel instance.

Path parameters

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchInteractionChannel() {
11  const channel = await client.flexApi.v1
12    .interaction("KDXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .fetch();
15
16  console.log(channel.sid);
17}
18
19fetchInteractionChannel();

Output

1{
2  "sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "type": "chat",
4  "interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "status": "closed",
6  "error_code": 19025,
7  "error_message": "Channel validation error",
8  "url": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
9  "links": {
10    "participants": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
11    "invites": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
12  }
13}

List Channels

GET /Interactions/<interaction_sid>/Channels

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

Response Object

Parameter	Description
sid	Unique identifier for the interaction channel
interaction_sid	Unique identifier for the interaction
	The channel type specified when the interaction was created. Please refer to the Interactions Properties table for possible values.
links	A JSON object linking to the interaction channel's associated participants and invites

List Channels

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchInteractionChannel() {
11  const channel = await client.flexApi.v1
12    .interaction("KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .fetch();
15
16  console.log(channel.sid);
17}
18
19fetchInteractionChannel();

Output

1{
2  "sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "type": "chat",
4  "interaction_sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "status": "closed",
6  "error_code": 19025,
7  "error_message": "Channel validation error",
8  "url": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
9  "links": {
10    "participants": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
11    "invites": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
12  }
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

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 status	Routing status	Resulting task state	Resulting conversation state
closed	Not specified	wrapping	closed
closed	closed	completed	closed

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.

Path parameters

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateInteractionChannelParticipant() {
11  const participant = await client.flexApi.v1
12    .interaction("KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .channels("UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .participants("UTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .update({ status: "closed" });
16
17  console.log(participant.sid);
18}
19
20updateInteractionChannelParticipant();

Output

1{
2  "sid": "UTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "channel_sid": "UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "interaction_sid": "KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "type": "agent",
6  "routing_properties": {
7    "task_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8    "worker_sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9    "reservation_sid": "WRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
10  },
11  "url": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants/UTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1"
12}

Close an Interaction Channel

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 status	Routing status	Resulting task state	Resulting conversation state
closed	Not specified	wrapping	closed
closed	closed	completed	closed

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.

Path parameters

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateInteractionChannel() {
11  const channel = await client.flexApi.v1
12    .interaction("KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .channels("UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({ status: "closed" });
15
16  console.log(channel.sid);
17}
18
19updateInteractionChannel();

Output

1{
2  "sid": "UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "interaction_sid": "KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "type": "chat",
5  "status": "closed",
6  "error_code": 19025,
7  "error_message": "Channel validation error",
8  "url": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
9  "links": {
10    "participants": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
11    "invites": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
12  }
13}

Close an interaction channel and complete all tasks

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateInteractionChannel() {
11  const channel = await client.flexApi.v1
12    .interaction("KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .channels("UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({
15      routing: {
16        status: "closed",
17      },
18      status: "closed",
19    });
20
21  console.log(channel.sid);
22}
23
24updateInteractionChannel();

Output

1{
2  "sid": "UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "interaction_sid": "KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "type": "chat",
5  "status": "closed",
6  "error_code": 19025,
7  "error_message": "Channel validation error",
8  "url": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
9  "links": {
10    "participants": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Participants",
11    "invites": "https://flex-api.twilio.com/v1/Interactions/KDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/UOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1/Invites"
12  }
13}