Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Roles

The Role resource of Programmable Chat represents what a user can do within a Chat Service instance. Roles are either Service scoped or 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 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:

account_sid
sid<AC> Not PII

The unique id of the Account responsible for this role.

date_created
date_time<iso8601> Not PII

The date that this resource was created in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date that this resource was last updated in ISO 8601 format.

friendly_name

The human-readable name of this role.

permissions
string[] Not PII

A JSON array of the permissions this role has. See the table below for a list of all possible permissions.

service_sid
sid<IS> Not PII

The unique id of the Service this role belongs to.

sid
sid<RL> Not PII

A 34 character string that uniquely identifies this resource.

type
enum:role_type Not PII

What kind of role this is. Either channel for Channel roles or deployment for Service roles.

url
url Not PII

An absolute URL for this role.

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
sendMediaMessage Allows the user to send media 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
deleteOwnMessage Allows user to delete their own messages 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

GET /Services/{Service SID}/Roles
Loading Code Sample...
      
      
      
      

      Create a Role

      POST /Services/{Service SID}/Roles
      

      Parameters

      FriendlyName
      Required
      post string PII MTL: 120 DAYS

      The human-readable name of this role.

      Permission
      Required
      post string[] Not PII

      (multiple) A permission this role should have. Consult the table above for the list of possible permissions.

      Type
      Required
      post enum:role_type Not PII

      What kind of role this is. Either channel for Channel roles or deployment for Service roles.

      Loading Code Sample...
          
          
          
          

          Retrieve a Role

          GET /Services/{Service SID}/Roles/{Role SID}
          
          Loading Code Sample...
              
              
              
              

              Update a Role

              POST /Services/{Service SID}/Roles/{Role SID}
              

              Note: This operation replaces the existing permissions on a Role, to add a permission you must also include any existing permissions in your request.

              Parameters

              Permission
              Required
              post string[] Not PII

              (multiple) A permission this role should have. Consult the table above for the list of possible permissions.

              Loading Code Sample...
                  
                  
                  
                  

                  Delete a Role

                  DELETE /Services/{Service SID}/Roles/{Role SID}
                  
                  Loading Code Sample...
                      
                      
                      
                      

                      Need some help?

                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                      Loading Code Sample...