0
# Chat Management
1
2
Chat administration capabilities including member management, permissions, invite links, and chat settings modification.
3
4
## Capabilities
5
6
### Chat Information
7
8
Retrieve information about chats, members, and administrative status.
9
10
```python { .api }
11
def get_chat(self, chat_id: Union[int, str]) -> types.Chat:
12
"""
13
Get up-to-date information about a chat.
14
15
Parameters:
16
- chat_id (Union[int, str]): Chat ID or username
17
18
Returns:
19
Chat: Chat information including type, title, member count, etc.
20
"""
21
22
def get_chat_administrators(self, chat_id: Union[int, str]) -> List[types.ChatMember]:
23
"""
24
Get list of administrators in a chat.
25
26
Parameters:
27
- chat_id (Union[int, str]): Chat ID or username
28
29
Returns:
30
List[ChatMember]: Array of chat administrators (except other bots)
31
"""
32
33
def get_chat_member_count(self, chat_id: Union[int, str]) -> int:
34
"""
35
Get the number of members in a chat.
36
37
Parameters:
38
- chat_id (Union[int, str]): Chat ID or username
39
40
Returns:
41
int: Number of members in the chat
42
"""
43
44
def get_chat_member(self, chat_id: Union[int, str], user_id: int) -> types.ChatMember:
45
"""
46
Get information about a chat member.
47
48
Parameters:
49
- chat_id (Union[int, str]): Chat ID or username
50
- user_id (int): User ID to get information about
51
52
Returns:
53
ChatMember: Member information and status
54
"""
55
56
def leave_chat(self, chat_id: Union[int, str]) -> bool:
57
"""
58
Leave a group, supergroup, or channel.
59
60
Parameters:
61
- chat_id (Union[int, str]): Chat ID or username
62
63
Returns:
64
bool: True on success
65
"""
66
```
67
68
### Member Management
69
70
Ban, unban, restrict, and promote chat members with granular permissions.
71
72
```python { .api }
73
def ban_chat_member(self, chat_id: Union[int, str], user_id: int,
74
until_date: Optional[Union[int, datetime]] = None,
75
revoke_messages: Optional[bool] = None) -> bool:
76
"""
77
Ban a user from a group, supergroup, or channel.
78
79
Parameters:
80
- chat_id (Union[int, str]): Chat ID or username
81
- user_id (int): User ID to ban
82
- until_date (Union[int, datetime], optional): Unban date (unix timestamp or datetime)
83
- revoke_messages (bool, optional): Delete all messages from the user
84
85
Returns:
86
bool: True on success
87
"""
88
89
def unban_chat_member(self, chat_id: Union[int, str], user_id: int,
90
only_if_banned: Optional[bool] = False) -> bool:
91
"""
92
Unban a previously banned user.
93
94
Parameters:
95
- chat_id (Union[int, str]): Chat ID or username
96
- user_id (int): User ID to unban
97
- only_if_banned (bool, optional): Only unban if currently banned
98
99
Returns:
100
bool: True on success
101
"""
102
103
def restrict_chat_member(self, chat_id: Union[int, str], user_id: int,
104
until_date: Optional[Union[int, datetime]] = None,
105
can_send_messages: Optional[bool] = None,
106
can_send_media_messages: Optional[bool] = None,
107
can_send_polls: Optional[bool] = None,
108
can_send_other_messages: Optional[bool] = None,
109
can_add_web_page_previews: Optional[bool] = None,
110
can_change_info: Optional[bool] = None,
111
can_invite_users: Optional[bool] = None,
112
can_pin_messages: Optional[bool] = None) -> bool:
113
"""
114
Restrict a user in a supergroup.
115
116
Parameters:
117
- chat_id (Union[int, str]): Chat ID or username
118
- user_id (int): User ID to restrict
119
- until_date (Union[int, datetime], optional): Restriction end date
120
- can_send_messages (bool, optional): Can send text messages
121
- can_send_media_messages (bool, optional): Can send media
122
- can_send_polls (bool, optional): Can send polls
123
- can_send_other_messages (bool, optional): Can send animations, games, stickers
124
- can_add_web_page_previews (bool, optional): Can add web page previews
125
- can_change_info (bool, optional): Can change chat info
126
- can_invite_users (bool, optional): Can invite new users
127
- can_pin_messages (bool, optional): Can pin messages
128
129
Returns:
130
bool: True on success
131
"""
132
133
def promote_chat_member(self, chat_id: Union[int, str], user_id: int,
134
can_change_info: Optional[bool] = None,
135
can_post_messages: Optional[bool] = None,
136
can_edit_messages: Optional[bool] = None,
137
can_delete_messages: Optional[bool] = None,
138
can_invite_users: Optional[bool] = None,
139
can_restrict_members: Optional[bool] = None,
140
can_pin_messages: Optional[bool] = None,
141
can_promote_members: Optional[bool] = None,
142
is_anonymous: Optional[bool] = None,
143
can_manage_chat: Optional[bool] = None,
144
can_manage_voice_chats: Optional[bool] = None) -> bool:
145
"""
146
Promote or demote a user in a supergroup or channel.
147
148
Parameters:
149
- chat_id (Union[int, str]): Chat ID or username
150
- user_id (int): User ID to promote
151
- can_change_info (bool, optional): Can change chat title, photo, etc.
152
- can_post_messages (bool, optional): Can create channel posts (channels only)
153
- can_edit_messages (bool, optional): Can edit messages (channels only)
154
- can_delete_messages (bool, optional): Can delete messages
155
- can_invite_users (bool, optional): Can invite new users
156
- can_restrict_members (bool, optional): Can restrict, ban, or unban members
157
- can_pin_messages (bool, optional): Can pin messages (supergroups only)
158
- can_promote_members (bool, optional): Can add new administrators
159
- is_anonymous (bool, optional): Administrator's presence is hidden
160
- can_manage_chat (bool, optional): Can access chat event log and statistics
161
- can_manage_voice_chats (bool, optional): Can manage voice chats
162
163
Returns:
164
bool: True on success
165
"""
166
```
167
168
### Chat Settings
169
170
Modify chat appearance, permissions, and configuration.
171
172
```python { .api }
173
def set_chat_photo(self, chat_id: Union[int, str], photo) -> bool:
174
"""
175
Set a new profile photo for the chat.
176
177
Parameters:
178
- chat_id (Union[int, str]): Chat ID or username
179
- photo: New chat photo (InputFile)
180
181
Returns:
182
bool: True on success
183
"""
184
185
def delete_chat_photo(self, chat_id: Union[int, str]) -> bool:
186
"""
187
Delete a chat photo.
188
189
Parameters:
190
- chat_id (Union[int, str]): Chat ID or username
191
192
Returns:
193
bool: True on success
194
"""
195
196
def set_chat_title(self, chat_id: Union[int, str], title: str) -> bool:
197
"""
198
Change the title of a chat.
199
200
Parameters:
201
- chat_id (Union[int, str]): Chat ID or username
202
- title (str): New chat title (1-255 characters)
203
204
Returns:
205
bool: True on success
206
"""
207
208
def set_chat_description(self, chat_id: Union[int, str], description: Optional[str] = None) -> bool:
209
"""
210
Change the description of a supergroup or channel.
211
212
Parameters:
213
- chat_id (Union[int, str]): Chat ID or username
214
- description (str, optional): New description (0-255 characters)
215
216
Returns:
217
bool: True on success
218
"""
219
220
def set_chat_permissions(self, chat_id: Union[int, str], permissions: types.ChatPermissions) -> bool:
221
"""
222
Set default chat permissions for all members.
223
224
Parameters:
225
- chat_id (Union[int, str]): Chat ID or username
226
- permissions (ChatPermissions): New default permissions
227
228
Returns:
229
bool: True on success
230
"""
231
```
232
233
### Invite Links
234
235
Create, edit, revoke, and export chat invite links.
236
237
```python { .api }
238
def create_chat_invite_link(self, chat_id: Union[int, str],
239
expire_date: Optional[Union[int, datetime]] = None,
240
member_limit: Optional[int] = None) -> types.ChatInviteLink:
241
"""
242
Create an additional invite link for a chat.
243
244
Parameters:
245
- chat_id (Union[int, str]): Chat ID or username
246
- expire_date (Union[int, datetime], optional): Link expiration date
247
- member_limit (int, optional): Maximum number of users (1-99999)
248
249
Returns:
250
ChatInviteLink: Created invite link
251
"""
252
253
def edit_chat_invite_link(self, chat_id: Union[int, str], invite_link: str,
254
expire_date: Optional[Union[int, datetime]] = None,
255
member_limit: Optional[int] = None) -> types.ChatInviteLink:
256
"""
257
Edit a non-primary invite link.
258
259
Parameters:
260
- chat_id (Union[int, str]): Chat ID or username
261
- invite_link (str): The invite link to edit
262
- expire_date (Union[int, datetime], optional): New expiration date
263
- member_limit (int, optional): New member limit
264
265
Returns:
266
ChatInviteLink: Edited invite link
267
"""
268
269
def revoke_chat_invite_link(self, chat_id: Union[int, str], invite_link: str) -> types.ChatInviteLink:
270
"""
271
Revoke an invite link.
272
273
Parameters:
274
- chat_id (Union[int, str]): Chat ID or username
275
- invite_link (str): The invite link to revoke
276
277
Returns:
278
ChatInviteLink: Revoked invite link
279
"""
280
281
def export_chat_invite_link(self, chat_id: Union[int, str]) -> str:
282
"""
283
Export an invite link to a supergroup or channel.
284
285
Parameters:
286
- chat_id (Union[int, str]): Chat ID or username
287
288
Returns:
289
str: Exported invite link
290
"""
291
```
292
293
### Message Pinning
294
295
Pin and unpin messages in chats.
296
297
```python { .api }
298
def pin_chat_message(self, chat_id: Union[int, str], message_id: int,
299
disable_notification: Optional[bool] = False) -> bool:
300
"""
301
Pin a message in a supergroup or channel.
302
303
Parameters:
304
- chat_id (Union[int, str]): Chat ID or username
305
- message_id (int): Message ID to pin
306
- disable_notification (bool, optional): Don't notify all members
307
308
Returns:
309
bool: True on success
310
"""
311
312
def unpin_chat_message(self, chat_id: Union[int, str], message_id: Optional[int] = None) -> bool:
313
"""
314
Unpin a specific pinned message in a supergroup.
315
316
Parameters:
317
- chat_id (Union[int, str]): Chat ID or username
318
- message_id (int, optional): Message ID to unpin (if not specified, unpins most recent)
319
320
Returns:
321
bool: True on success
322
"""
323
324
def unpin_all_chat_messages(self, chat_id: Union[int, str]) -> bool:
325
"""
326
Unpin all pinned messages in a supergroup.
327
328
Parameters:
329
- chat_id (Union[int, str]): Chat ID or username
330
331
Returns:
332
bool: True on success
333
"""
334
```
335
336
## Usage Examples
337
338
### Basic Chat Management
339
340
```python
341
# Get chat information
342
chat = bot.get_chat("@mychannel")
343
print(f"Chat title: {chat.title}")
344
print(f"Member count: {bot.get_chat_member_count(chat.id)}")
345
346
# Get administrators
347
admins = bot.get_chat_administrators(chat.id)
348
for admin in admins:
349
print(f"Admin: {admin.user.first_name}")
350
```
351
352
### Member Moderation
353
354
```python
355
@bot.message_handler(commands=['ban'])
356
def ban_user(message):
357
if message.reply_to_message:
358
user_id = message.reply_to_message.from_user.id
359
bot.ban_chat_member(message.chat.id, user_id)
360
bot.reply_to(message, "User banned!")
361
362
@bot.message_handler(commands=['restrict'])
363
def restrict_user(message):
364
if message.reply_to_message:
365
user_id = message.reply_to_message.from_user.id
366
bot.restrict_chat_member(
367
message.chat.id,
368
user_id,
369
can_send_messages=False,
370
until_date=datetime.now() + timedelta(hours=1)
371
)
372
bot.reply_to(message, "User restricted for 1 hour!")
373
```
374
375
### Chat Settings Management
376
377
```python
378
@bot.message_handler(commands=['settitle'])
379
def set_title(message):
380
args = message.text.split(maxsplit=1)
381
if len(args) > 1:
382
new_title = args[1]
383
bot.set_chat_title(message.chat.id, new_title)
384
bot.reply_to(message, f"Title changed to: {new_title}")
385
386
@bot.message_handler(commands=['pin'])
387
def pin_message(message):
388
if message.reply_to_message:
389
bot.pin_chat_message(message.chat.id, message.reply_to_message.message_id)
390
bot.reply_to(message, "Message pinned!")
391
```
392
393
## Types
394
395
```python { .api }
396
class Chat:
397
id: int
398
type: str # 'private', 'group', 'supergroup', 'channel'
399
title: Optional[str]
400
username: Optional[str]
401
first_name: Optional[str]
402
last_name: Optional[str]
403
photo: Optional[ChatPhoto]
404
bio: Optional[str]
405
description: Optional[str]
406
invite_link: Optional[str]
407
pinned_message: Optional[Message]
408
permissions: Optional[ChatPermissions]
409
# ... additional fields
410
411
class ChatMember:
412
user: User
413
status: str # 'creator', 'administrator', 'member', 'restricted', 'left', 'kicked'
414
custom_title: Optional[str]
415
is_anonymous: Optional[bool]
416
until_date: Optional[int]
417
# ... permission fields
418
419
class ChatPermissions:
420
can_send_messages: Optional[bool]
421
can_send_media_messages: Optional[bool]
422
can_send_polls: Optional[bool]
423
can_send_other_messages: Optional[bool]
424
can_add_web_page_previews: Optional[bool]
425
can_change_info: Optional[bool]
426
can_invite_users: Optional[bool]
427
can_pin_messages: Optional[bool]
428
429
class ChatInviteLink:
430
invite_link: str
431
creator: User
432
creates_join_request: bool
433
is_primary: bool
434
is_revoked: bool
435
name: Optional[str]
436
expire_date: Optional[int]
437
member_limit: Optional[int]
438
pending_join_request_count: Optional[int]
439
```