Channels Resource

(error)

Programmable Chat deprecated

Programmable Chat has been deprecated and receives no support. Twilio has turned its focus to the next generation of chat: Twilio Conversations. Find out more about the EOL process.

To start a project, see Conversations.
To switch from Programmable Chat, see the Migration Guide to learn about how to switch.

(error)

Danger

This is reference documentation for the v1 REST API, which has been deprecated. You should use the current v2 REST API.

The Channel resource of Programmable Chat represents a "chat room" - a scope in which Messages can be sent and received. Members can be added or invited to join channels. Channels exist within a Chat Service scope.

Channels can also have an optional, addressable Unique Name. This allows for a channel to be named something specific, and be looked up and addressed directly. The Unique Name is enforced as unique within the Service instance.

Twilio Console

To view your Chat Channels, open the Programmable Chat Services page in the Twilio Console. Within a Service, you can browse the Channels that belong to that Service.

Properties

Each channel has these properties:

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<CH>

Optional

Not PII

The unique string that we created to identify the Channel resource.

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

accountSidSID<AC>

Optional

Not PII

The SID of the Account that created the Channel resource.

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

serviceSidSID<IS>

Optional

Not PII

The SID of the Service the resource is associated with.

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

friendlyNamestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

uniqueNamestring

Optional

PII MTL: 30 days

An application-defined string that uniquely identifies the resource. It can be used to address the resource in place of the resource's sid in the URL.

attributesstring

Optional

PII MTL: 30 days

The JSON string that stores application-specific data. Note If this property has been assigned a value, it's only displayed in a FETCH action that returns a single resource; otherwise, it's null. If the attributes have not been set, {} is returned.

typeenum<string>

Optional

Not PII

The visibility of the channel. Can be: public or private.

Possible values:

publicprivate

dateCreatedstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

dateUpdatedstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

createdBystring

Optional

PII MTL: 30 days

The identity of the User that created the channel. If the Channel was created by using the API, the value is system.

membersCountinteger

Optional

Not PII

The number of Members in the Channel.

Default: 0

messagesCountinteger

Optional

Not PII

The number of Messages in the Channel.

Default: 0

urlstring<uri>

Optional

Not PII

The absolute URL of the Channel resource.

linksobject<uri-map>

Optional

Not PII

The absolute URLs of the Members, Messages , Invites and, if it exists, the last Message for the Channel.

List All Channels

1GET /Services/{Instance SID}/Channels
2

List all 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 listChannel() {
11  const channels = await client.chat.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .channels.list({ limit: 20 });
14
15  channels.forEach((c) => console.log(c.sid));
16}
17
18listChannel();

Response

1{
2  "channels": [
3    {
4      "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "friendly_name": "friendly_name",
8      "unique_name": "unique_name",
9      "attributes": "{ \"foo\": \"bar\" }",
10      "type": "public",
11      "date_created": "2015-12-16T22:18:37Z",
12      "date_updated": "2015-12-16T22:18:37Z",
13      "created_by": "system",
14      "members_count": 0,
15      "messages_count": 0,
16      "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "links": {
18        "members": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Members",
19        "messages": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
20        "invites": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Invites",
21        "last_message": null
22      }
23    }
24  ],
25  "meta": {
26    "page": 0,
27    "page_size": 50,
28    "first_page_url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels?PageSize=50&Page=0",
29    "previous_page_url": null,
30    "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels?PageSize=50&Page=0",
31    "next_page_url": null,
32    "key": "channels"
33  }
34}

Create a Channel

1POST /Services/{Instance SID}/Channels
2

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

Not PII

The SID of the Service to create the resource under.

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

Request body parameters

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

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

friendlyNamestring

Optional

PII MTL: 30 days

A descriptive string that you create to describe the new resource. It can be up to 64 characters long.

uniqueNamestring

Optional

PII MTL: 30 days

An application-defined string that uniquely identifies the resource. It can be used to address the resource in place of the resource's sid in the URL. This value must be 64 characters or less in length and be unique within the Service.

attributesstring

Optional

PII MTL: 30 days

A valid JSON string that contains application-specific data.

typeenum<string>

Optional

Not PII

The visibility of the channel. Can be: public or private.

Possible values:

publicprivate

Create 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 createChannel() {
11  const channel = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels.create({ friendlyName: "MyChannel" });
14
15  console.log(channel.sid);
16}
17
18createChannel();

Response

1{
2  "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "MyChannel",
6  "unique_name": "unique_name",
7  "attributes": "{ \"foo\": \"bar\" }",
8  "type": "public",
9  "date_created": "2015-12-16T22:18:37Z",
10  "date_updated": "2015-12-16T22:18:37Z",
11  "created_by": "system",
12  "members_count": 0,
13  "messages_count": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "members": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Members",
17    "messages": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
18    "invites": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Invites",
19    "last_message": null
20  }
21}

Retrieve a Channel

1GET /Services/{Instance SID}/Channels/{Channel SID}
2

1GET /Services/{Instance SID}/Channels/{Unique Name}
2

Retrieve 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 fetchChannel() {
11  const channel = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .fetch();
15
16  console.log(channel.sid);
17}
18
19fetchChannel();

Response

1{
2  "sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "friendly_name",
6  "unique_name": "unique_name",
7  "attributes": "{ \"foo\": \"bar\" }",
8  "type": "public",
9  "date_created": "2015-12-16T22:18:37Z",
10  "date_updated": "2015-12-16T22:18:37Z",
11  "created_by": "system",
12  "members_count": 0,
13  "messages_count": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "members": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Members",
17    "messages": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
18    "invites": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Invites",
19    "last_message": null
20  }
21}

Update a Channel

1POST /Services/{Instance SID}/Channels/{Channel SID}
2

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

Not PII

The SID of the Service to update the resource from.

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

sidstring

required

Not PII

The Twilio-provided string that uniquely identifies the Channel resource to update.

Request body parameters

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

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

friendlyNamestring

Optional

PII MTL: 30 days

A descriptive string that you create to describe the resource. It can be up to 64 characters long.

uniqueNamestring

Optional

PII MTL: 30 days

attributesstring

Optional

PII MTL: 30 days

A valid JSON string that contains application-specific data.

Update 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 updateChannel() {
11  const channel = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .update({ friendlyName: "NEW_FRIENDLY_NAME" });
15
16  console.log(channel.sid);
17}
18
19updateChannel();

Response

1{
2  "sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "NEW_FRIENDLY_NAME",
6  "unique_name": "unique_name",
7  "attributes": "{ \"foo\": \"bar\" }",
8  "type": "public",
9  "date_created": "2015-12-16T22:18:37Z",
10  "date_updated": "2015-12-16T22:18:37Z",
11  "created_by": "system",
12  "members_count": 0,
13  "messages_count": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "members": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Members",
17    "messages": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
18    "invites": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Invites",
19    "last_message": null
20  }
21}

Delete a Channel

1DELETE /Services/{Instance SID}/Channels/{Channel SID}
2

Delete 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 deleteChannel() {
11  await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .remove();
15}
16
17deleteChannel();