Skip to content Skip to navigation Skip to topbar

On this page

Roles

(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 Role resource of Programmable Chat represents what a user can do within a Chat Service instance. Roles are either [Service][service] scoped or [Channel][channel] scoped.

Users are assigned a role at the Service scope, which determines what they are able to do within the Chat Service instance - e.g. create channels, destroy channels, and more.

[Members][member] are also assigned a role at the Channel scope, per channel. This determines what they are able to do within a particular channel - e.g. invite users to be members of the channel, post messages, kick members from the channel, and more.

Properties

Each role has these properties:

Property nameTypeRequiredDescriptionChild properties

sidSID<RL>

Optional

Not PII

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

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

account_sidSID<AC>

Optional

Not PII

The SID of the Account that created the Role 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.

typeenum<string>

Optional

Not PII

The type of role. Can be: channel for Channel roles or deployment for Service roles.

Possible values:

channeldeployment

permissionsarray[string]

Optional

Not PII

An array of the permissions the role has been granted, formatted as a JSON string.

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.

urlstring<uri>

Optional

Not PII

The absolute URL of the Role resource.

This is the complete list of possible permissions entries for deployment (Service) roles:

name	description
createChannel	Allows users to create new channels
joinChannel	Allows users to join channels
destroyChannel	Allows users to delete channels
inviteMember	Allows users to invite other users to be members of a channel
removeMember	Allows users to remove members from a channel
editChannelName	Allows users to change the name of a channel
editChannelAttributes	Allows users to update the optional `attributes` metadata field on a channel
addMember	Allows users to add other users as members of a channel
editOwnMessage	Allows users to edit their own messages in the Service
editAnyMessage	Allows users to edit any message in the Service
editOwnMessageAttributes	Allows users to edit the own message attributes in the Service
editAnyMessageAttributes	Allows users to edit any message attributes in the Service
deleteAnyMessage	Allows users to delete any message in the Service
editOwnUserInfo	Allows users to edit their own User Info properties
editAnyUserInfo	Allows users to edit other User's User Info properties

This is the complete list of possible permissions entries for channel roles:

name	description
sendMessage	Allows the user to send messages to channels
leaveChannel	Allows users to leave a channel
destroyChannel	Allows users to delete channels
inviteMember	Allows users to invite other users to be members of a channel
removeMember	Allows users to remove members from a channel
editChannelName	Allows users to change the name of a channel
editChannelAttributes	Allows users to update the optional `attributes` metadata field on a channel
addMember	Allows users to add other users as members of a channel
editOwnMessage	Allows users to edit their own messages in the Service
editAnyMessage	Allows users to edit any message in the Service
editOwnMessageAttributes	Allows users to edit the own message attributes in the Service
editAnyMessageAttributes	Allows users to edit any message attributes in the Service
deleteAnyMessage	Allows users to delete any message in the Service
editOwnUserInfo	Allows users to edit their own User Info properties
editAnyUserInfo	Allows users to edit other User's User Info properties

List All Roles

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

List all Roles

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 listRole() {
11  const roles = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .roles.list({ limit: 20 });
14
15  roles.forEach((r) => console.log(r.sid));
16}
17
18listRole();

Output

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "roles"
10  },
11  "roles": [
12    {
13      "sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "friendly_name": "channel user",
17      "type": "channel",
18      "permissions": [
19        "sendMessage",
20        "leaveChannel",
21        "editOwnMessage",
22        "deleteOwnMessage"
23      ],
24      "date_created": "2016-03-03T19:47:15Z",
25      "date_updated": "2016-03-03T19:47:15Z",
26      "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles/RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
27    }
28  ]
29}

Create a Role

1POST /Services/{Instance SID}/Roles
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

FriendlyNamestringrequired

PII MTL: 30 days

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

Typeenum<string>required

Not PII

The type of role. Can be: channel for Channel roles or deployment for Service roles.

Possible values:

channeldeployment

Permissionarray[string]required

Not PII

A permission that you grant to the new role. Only one permission can be granted per parameter. To assign more than one permission, repeat this parameter for each permission value. The values for this parameter depend on the role's type and are described in the documentation.

Create a Role

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 createRole() {
11  const role = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .roles.create({
14      friendlyName: "new_role",
15      permission: ["createChannel"],
16      type: "deployment",
17    });
18
19  console.log(role.sid);
20}
21
22createRole();

Output

1{
2  "sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "new_role",
6  "type": "deployment",
7  "permissions": [
8    "sendMessage",
9    "leaveChannel",
10    "editOwnMessage",
11    "deleteOwnMessage"
12  ],
13  "date_created": "2016-03-03T19:47:15Z",
14  "date_updated": "2016-03-03T19:47:15Z",
15  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles/RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16}

Retrieve a Role

1GET /Services/{Instance SID}/Roles/{Role SID}
2

Retrieve a Role

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

Output

1{
2  "sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "channel user",
6  "type": "channel",
7  "permissions": [
8    "sendMessage",
9    "leaveChannel",
10    "editOwnMessage",
11    "deleteOwnMessage"
12  ],
13  "date_created": "2016-03-03T19:47:15Z",
14  "date_updated": "2016-03-03T19:47:15Z",
15  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles/RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16}

Update a Role

1POST /Services/{Instance SID}/Roles/{Role 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

SidSID<RL>required

Not PII

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

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

Request body parameters

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

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Permissionarray[string]required

Not PII

A permission that you grant to the role. Only one permission can be granted per parameter. To assign more than one permission, repeat this parameter for each permission value. The values for this parameter depend on the role's type and are described in the documentation.

Update a Role

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 updateRole() {
11  const role = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .roles("RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .update({ permission: ["sendMediaMessage"] });
15
16  console.log(role.sid);
17}
18
19updateRole();

Output

1{
2  "sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "friendly_name": "channel user",
6  "type": "channel",
7  "permissions": [
8    "sendMessage",
9    "leaveChannel",
10    "editOwnMessage",
11    "deleteOwnMessage"
12  ],
13  "date_created": "2016-03-03T19:47:15Z",
14  "date_updated": "2016-03-03T19:47:15Z",
15  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles/RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16}

Delete a Role

1DELETE /Services/{Instance SID}/Roles/{Role SID}
2

Delete a Role

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