0
# Roles
1

2
Role management system for Rocket.Chat server administration. Provides functionality for creating, listing, and managing user roles with optional room-specific scope.
3

4
## Capabilities
5

6
### Role Information
7

8
```python { .api }
9
def roles_list(self, **kwargs):
10
    """
11
    Get all roles in the system.
12
    
13
    Returns:
14
    requests.Response: List of all system roles
15
    """
16

17
def roles_get_users_in_role(self, role, **kwargs):
18
    """
19
    Get users that belong to a specific role.
20
    
21
    Parameters:
22
    - role (str): Role name
23
    - offset (int, optional): Number of items to skip
24
    - count (int, optional): Number of items to return
25
    
26
    Returns:
27
    requests.Response: List of users in the role
28
    """
29

30
def roles_sync(self, updated_since):
31
    """
32
    Get all roles updated after a given date.
33
    
34
    Parameters:
35
    - updated_since (str): ISO date string (e.g., '2023-01-01T00:00:00.000Z')
36
    
37
    Returns:
38
    requests.Response: Updated roles
39
    """
40
```
41

42
### Role Creation
43

44
```python { .api }
45
def roles_create(self, name, **kwargs):
46
    """
47
    Create a new role in the system.
48
    
49
    Parameters:
50
    - name (str): Role name
51
    - scope (str, optional): Role scope ('Global' or 'Rooms')
52
    - description (str, optional): Role description
53
    
54
    Returns:
55
    requests.Response: Role creation result
56
    """
57
```
58

59
### User-Role Assignment
60

61
```python { .api }
62
def roles_add_user_to_role(self, role_name, username, **kwargs):
63
    """
64
    Assign a role to a user.
65
    
66
    Parameters:
67
    - role_name (str): Role name to assign
68
    - username (str): Username to assign role to
69
    - roomId (str, optional): Room ID for room-specific role assignment
70
    
71
    Returns:
72
    requests.Response: Role assignment result
73
    """
74

75
def roles_remove_user_from_role(self, role_name, username, **kwargs):
76
    """
77
    Remove a role from a user.
78
    
79
    Parameters:
80
    - role_name (str): Role name to remove
81
    - username (str): Username to remove role from
82
    - roomId (str, optional): Room ID for room-specific role removal
83
    
84
    Returns:
85
    requests.Response: Role removal result
86
    """
87
```
88

89
## Common Rocket.Chat Roles
90

91
```python { .api }
92
DefaultRoles = [
93
    "admin",        # Server administrator
94
    "moderator",    # Channel/room moderator
95
    "owner",        # Channel/room owner
96
    "user",         # Regular user
97
    "bot",          # Bot account
98
    "app",          # Application account
99
    "guest",        # Guest user
100
    "anonymous",    # Anonymous user
101
    "livechat-agent",    # LiveChat agent
102
    "livechat-manager",  # LiveChat manager
103
    "leader"        # Channel/room leader
104
]
105
```
106

107
## Usage Examples
108

109
```python
110
# List all roles
111
roles = rocket.roles_list()
112
print(roles.json())
113

114
# Create a new role
115
new_role = rocket.roles_create(
116
    name='custom-moderator',
117
    scope='Rooms',
118
    description='Custom moderator role with limited permissions'
119
)
120

121
# Assign role to user
122
rocket.roles_add_user_to_role(
123
    role_name='moderator',
124
    username='john.doe'
125
)
126

127
# Assign room-specific role
128
rocket.roles_add_user_to_role(
129
    role_name='owner',
130
    username='alice.smith',
131
    roomId='GENERAL'
132
)
133

134
# Remove role from user
135
rocket.roles_remove_user_from_role(
136
    role_name='moderator',
137
    username='john.doe'
138
)
139

140
# Get users in a role
141
moderators = rocket.roles_get_users_in_role('moderator')
142
print(f"Moderators: {moderators.json()}")
143

144
# Sync roles updated since date
145
from datetime import datetime, timedelta
146
yesterday = (datetime.now() - timedelta(days=1)).isoformat() + 'Z'
147
updated_roles = rocket.roles_sync(yesterday)
148
```