0
# Rooms
1
2
Advanced room operations and management functionality that works across all room types (channels, groups, direct messages). Provides file upload, history management, favorites, and administrative functions.
3
4
## Capabilities
5
6
### Room Information
7
8
```python { .api }
9
def rooms_get(self, **kwargs):
10
"""
11
Get all opened rooms for the current user.
12
13
Parameters:
14
- updatedSince (str, optional): ISO date string to get rooms updated since
15
16
Returns:
17
requests.Response: List of user's opened rooms
18
"""
19
20
def rooms_info(self, room_id=None, room_name=None):
21
"""
22
Get information about a specific room.
23
24
Parameters:
25
- room_id (str, optional): Room ID
26
- room_name (str, optional): Room name
27
28
Returns:
29
requests.Response: Room information
30
"""
31
32
def rooms_admin_rooms(self, **kwargs):
33
"""
34
Get all rooms (requires view-room-administration permission).
35
36
Parameters:
37
- offset (int, optional): Number of items to skip
38
- count (int, optional): Number of items to return
39
- sort (dict, optional): Sort criteria
40
- filter (str, optional): Filter rooms by name
41
- types (list, optional): Room types to include
42
43
Returns:
44
requests.Response: List of all rooms
45
"""
46
```
47
48
### File Operations
49
50
```python { .api }
51
def rooms_upload(self, rid, file, **kwargs):
52
"""
53
Upload a file to a room.
54
55
Parameters:
56
- rid (str): Room ID
57
- file (str): File path to upload
58
- description (str, optional): File description
59
- msg (str, optional): Message to accompany the file
60
61
Returns:
62
requests.Response: File upload result
63
"""
64
```
65
66
### Room Management
67
68
```python { .api }
69
def rooms_favorite(self, room_id=None, room_name=None, favorite=True):
70
"""
71
Mark a room as favorite or unfavorite.
72
73
Parameters:
74
- room_id (str, optional): Room ID
75
- room_name (str, optional): Room name
76
- favorite (bool): True to favorite, False to unfavorite
77
78
Returns:
79
requests.Response: Favorite operation result
80
"""
81
82
def rooms_leave(self, room_id):
83
"""
84
Leave a room.
85
86
Parameters:
87
- room_id (str): Room ID to leave
88
89
Returns:
90
requests.Response: Leave operation result
91
"""
92
```
93
94
### History Management
95
96
```python { .api }
97
def rooms_clean_history(self, room_id, latest, oldest, **kwargs):
98
"""
99
Clean room history by removing messages from a time range.
100
101
Parameters:
102
- room_id (str): Room ID
103
- latest (str): Latest date (ISO string or timestamp)
104
- oldest (str): Oldest date (ISO string or timestamp)
105
- exclusive (bool, optional): Exclude boundary messages
106
- ignoreDiscussion (bool, optional): Ignore discussion messages
107
- filesOnly (bool, optional): Delete only files
108
- users (list, optional): Only delete messages from specific users
109
110
Returns:
111
requests.Response: History cleaning result
112
"""
113
```
114
115
### Discussion Management
116
117
```python { .api }
118
def rooms_create_discussion(self, prid, t_name, **kwargs):
119
"""
120
Create a new discussion for a room.
121
122
Parameters:
123
- prid (str): Parent room ID
124
- t_name (str): Discussion name
125
- reply (str, optional): Message ID to start discussion from
126
- users (list, optional): Users to add to discussion
127
- encrypted (bool, optional): Create encrypted discussion
128
129
Returns:
130
requests.Response: Discussion creation result
131
"""
132
```
133
134
## Room Object Structure
135
136
```python { .api }
137
RoomObject = {
138
"_id": "str", # Room ID
139
"name": "str", # Room name
140
"t": "str", # Room type (c=channel, p=group, d=direct)
141
"u": { # Creator user info
142
"_id": "str",
143
"username": "str"
144
},
145
"topic": "str", # Room topic
146
"description": "str", # Room description
147
"announcement": "str", # Room announcement
148
"msgs": "int", # Message count
149
"usersCount": "int", # User count
150
"lastMessage": "dict", # Last message info
151
"ts": "datetime", # Creation timestamp
152
"_updatedAt": "datetime", # Last update timestamp
153
"ro": "bool", # Read-only status
154
"sysMes": "bool", # System messages enabled
155
"default": "bool", # Default channel
156
"featured": "bool", # Featured status
157
"favorite": "bool", # User's favorite status
158
"open": "bool", # Open for user
159
"alert": "bool", # Has unread messages
160
"unread": "int", # Unread message count
161
"userMentions": "int", # User mention count
162
"groupMentions": "int" # Group mention count
163
}
164
```
165
166
## Usage Examples
167
168
```python
169
# Get all user's rooms
170
rooms = rocket.rooms_get()
171
print(f"User has {len(rooms.json()['rooms'])} rooms")
172
173
# Get room information
174
room_info = rocket.rooms_info(room_name='general')
175
room_id = room_info.json()['room']['_id']
176
177
# Upload file to room
178
upload_result = rocket.rooms_upload(
179
rid=room_id,
180
file='/path/to/document.pdf',
181
description='Important document',
182
msg='Please review this document'
183
)
184
185
# Favorite a room
186
rocket.rooms_favorite(room_id=room_id, favorite=True)
187
188
# Clean room history (remove messages from last 7 days)
189
from datetime import datetime, timedelta
190
now = datetime.now()
191
week_ago = now - timedelta(days=7)
192
193
rocket.rooms_clean_history(
194
room_id=room_id,
195
latest=now.isoformat(),
196
oldest=week_ago.isoformat(),
197
filesOnly=False
198
)
199
200
# Create discussion
201
discussion = rocket.rooms_create_discussion(
202
prid=room_id,
203
t_name='Project Planning Discussion',
204
users=['john.doe', 'jane.smith']
205
)
206
207
# Leave room
208
rocket.rooms_leave(room_id)
209
```