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:

Names in Ruby format
sid
sid<RL> Not PII

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

account_sid
sid<AC> Not PII

The SID of the Account that created the Role resource.

service_sid
sid<IS> Not PII

The SID of the Service the resource is associated with.

friendly_name

The string that you assigned to describe the resource.

type
enum:role_type Not PII

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

permissions
string[] Not PII

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

date_created
date_time<iso8601> Not PII

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

date_updated
date_time<iso8601> Not PII

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

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

        Create a Role

        POST /Services/{Service SID}/Roles
        

        Parameters

        Names in Ruby format
        service_sid
        Required
        post sid<IS> Not PII

        The SID of the Service to create the resource under.

        friendly_name
        Required
        post string PII MTL: 120 DAYS

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

        type
        Required
        post enum:role_type Not PII

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

        permission
        Required
        post string[] 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.

              
              
              
              

              Retrieve a Role

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

                    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

                    Names in Ruby format
                    service_sid
                    Required
                    post sid<IS> Not PII

                    The SID of the Service to update the resource from.

                    sid
                    Required
                    post sid<RL> Not PII

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

                    permission
                    Required
                    post string[] 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.

                          
                          
                          
                          

                          Delete a Role

                          DELETE /Services/{Service SID}/Roles/{Role SID}
                          
                                
                                
                                
                                
                                Rate this page:

                                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.