Skip to content Skip to navigation Skip to topbar

On this page

Channels Resource

(error)

Danger

Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here.

If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our 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

You can view your Chat Channels using your Twilio console when logged in to the console. Within a Service, you will be able to browse the Channels within the Service.

Properties

Each channel has these properties:

Property nameTypeRequiredDescriptionChild 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

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

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

friendly_namestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

unique_namestring

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

date_createdstring<date-time>

Optional

Not PII

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

date_updatedstring<date-time>

Optional

Not PII

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

created_bystring

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.

members_countinteger

Optional

Not PII

The number of Members in the Channel.

Default: 0

messages_countinteger

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();

Output

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

Parameters

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 nameTypeRequiredDescriptionChild 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 and defaults to public.

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();

Output

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();

Output

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

Parameters

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

Sidstringrequired

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 nameTypeRequiredDescriptionChild 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();

Output

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();