0
# Chat and User Management
1

2
Complete chat administration including member management, permissions, roles, and chat settings with support for groups, supergroups, and channels.
3

4
## Capabilities
5

6
### Chat Information
7

8
Methods for retrieving information about chats, members, and administrators.
9

10
```javascript { .api }
11
/**
12
 * Get chat information
13
 * @param {number|string} chatId - Chat identifier
14
 * @param {object} [options] - Additional options
15
 * @returns {Promise<Chat>}
16
 */
17
getChat(chatId, options): Promise<Chat>;
18

19
/**
20
 * Get list of chat administrators
21
 * @param {number|string} chatId - Chat identifier
22
 * @param {object} [options] - Additional options
23
 * @returns {Promise<ChatMember[]>}
24
 */
25
getChatAdministrators(chatId, options): Promise<ChatMember[]>;
26

27
/**
28
 * Get number of chat members
29
 * @param {number|string} chatId - Chat identifier
30
 * @param {object} [options] - Additional options
31
 * @returns {Promise<number>}
32
 */
33
getChatMemberCount(chatId, options): Promise<number>;
34

35
/**
36
 * Get chat member information
37
 * @param {number|string} chatId - Chat identifier
38
 * @param {number} userId - User identifier
39
 * @param {object} [options] - Additional options
40
 * @returns {Promise<ChatMember>}
41
 */
42
getChatMember(chatId, userId, options): Promise<ChatMember>;
43
```
44

45
**Usage Example:**
46

47
```javascript
48
// Get detailed chat information
49
const chat = await bot.getChat(chatId);
50
console.log(`Chat: ${chat.title || chat.first_name}`);
51
console.log(`Type: ${chat.type}`);
52
console.log(`Members: ${chat.member_count || 'N/A'}`);
53

54
if (chat.description) {
55
  console.log(`Description: ${chat.description}`);
56
}
57

58
// Get chat administrators
59
const admins = await bot.getChatAdministrators(chatId);
60
console.log(`Chat has ${admins.length} administrators:`);
61

62
admins.forEach(admin => {
63
  const user = admin.user;
64
  const status = admin.status;
65
  console.log(`- ${user.first_name} (${user.username || user.id}) - ${status}`);
66
  
67
  if (admin.custom_title) {
68
    console.log(`  Custom title: ${admin.custom_title}`);
69
  }
70
});
71

72
// Get member count
73
const memberCount = await bot.getChatMemberCount(chatId);
74
console.log(`Total members: ${memberCount}`);
75

76
// Check specific user status
77
const member = await bot.getChatMember(chatId, userId);
78
console.log(`User status: ${member.status}`);
79

80
if (member.status === 'restricted') {
81
  console.log('User restrictions:', member.permissions);
82
}
83
```
84

85
### Member Management
86

87
Methods for managing chat members including banning, unbanning, and permission management.
88

89
```javascript { .api }
90
/**
91
 * Ban user from chat
92
 * @param {number|string} chatId - Chat identifier
93
 * @param {number} userId - User identifier
94
 * @param {object} [options] - Ban options
95
 * @returns {Promise<boolean>}
96
 */
97
banChatMember(chatId, userId, options): Promise<boolean>;
98

99
/**
100
 * Unban user from chat
101
 * @param {number|string} chatId - Chat identifier
102
 * @param {number} userId - User identifier
103
 * @param {object} [options] - Unban options
104
 * @returns {Promise<boolean>}
105
 */
106
unbanChatMember(chatId, userId, options): Promise<boolean>;
107

108
/**
109
 * Restrict chat member permissions
110
 * @param {number|string} chatId - Chat identifier
111
 * @param {number} userId - User identifier
112
 * @param {object} permissions - Chat permissions
113
 * @param {object} [options] - Additional options
114
 * @returns {Promise<boolean>}
115
 */
116
restrictChatMember(chatId, userId, permissions, options): Promise<boolean>;
117

118
/**
119
 * Promote/demote chat member to administrator
120
 * @param {number|string} chatId - Chat identifier
121
 * @param {number} userId - User identifier
122
 * @param {object} [options] - Promotion options
123
 * @returns {Promise<boolean>}
124
 */
125
promoteChatMember(chatId, userId, options): Promise<boolean>;
126

127
/**
128
 * Set custom title for administrator
129
 * @param {number|string} chatId - Chat identifier
130
 * @param {number} userId - User identifier
131
 * @param {string} customTitle - Custom title (0-16 characters)
132
 * @param {object} [options] - Additional options
133
 * @returns {Promise<boolean>}
134
 */
135
setChatAdministratorCustomTitle(chatId, userId, customTitle, options): Promise<boolean>;
136
```
137

138
**Usage Example:**
139

140
```javascript
141
// Ban user with time limit
142
await bot.banChatMember(chatId, userId, {
143
  until_date: Math.floor(Date.now() / 1000) + 3600, // 1 hour ban
144
  revoke_messages: true // Delete messages from user
145
});
146

147
// Permanent ban
148
await bot.banChatMember(chatId, userId, {
149
  revoke_messages: false
150
});
151

152
// Unban user
153
await bot.unbanChatMember(chatId, userId, {
154
  only_if_banned: true
155
});
156

157
// Restrict user permissions
158
await bot.restrictChatMember(chatId, userId, {
159
  can_send_messages: false,
160
  can_send_audios: false,
161
  can_send_documents: false,
162
  can_send_photos: false,
163
  can_send_videos: false,
164
  can_send_video_notes: false,
165
  can_send_voice_notes: false,
166
  can_send_polls: false,
167
  can_send_other_messages: false,
168
  can_add_web_page_previews: false,
169
  can_change_info: false,
170
  can_invite_users: false,
171
  can_pin_messages: false,
172
  can_manage_topics: false
173
}, {
174
  until_date: Math.floor(Date.now() / 1000) + 1800 // 30 minutes
175
});
176

177
// Promote user to administrator
178
await bot.promoteChatMember(chatId, userId, {
179
  is_anonymous: false,
180
  can_manage_chat: false,
181
  can_delete_messages: true,
182
  can_manage_video_chats: false,
183
  can_restrict_members: true,
184
  can_promote_members: false,
185
  can_change_info: false,
186
  can_invite_users: true,
187
  can_post_messages: false, // for channels
188
  can_edit_messages: false, // for channels
189
  can_pin_messages: true,
190
  can_manage_topics: false // for forum supergroups
191
});
192

193
// Set custom administrator title
194
await bot.setChatAdministratorCustomTitle(chatId, userId, '🛡️ Moderator');
195
```
196

197
### Channel and Sender Chat Management
198

199
Methods for managing channel chats in supergroups.
200

201
```javascript { .api }
202
/**
203
 * Ban channel chat in supergroup
204
 * @param {number|string} chatId - Chat identifier
205
 * @param {number} senderChatId - Sender chat identifier
206
 * @param {object} [options] - Additional options
207
 * @returns {Promise<boolean>}
208
 */
209
banChatSenderChat(chatId, senderChatId, options): Promise<boolean>;
210

211
/**
212
 * Unban channel chat in supergroup
213
 * @param {number|string} chatId - Chat identifier
214
 * @param {number} senderChatId - Sender chat identifier
215
 * @param {object} [options] - Additional options
216
 * @returns {Promise<boolean>}
217
 */
218
unbanChatSenderChat(chatId, senderChatId, options): Promise<boolean>;
219
```
220

221
**Usage Example:**
222

223
```javascript
224
// Ban a channel from posting in supergroup
225
await bot.banChatSenderChat(supergroupId, channelId);
226

227
// Unban a channel
228
await bot.unbanChatSenderChat(supergroupId, channelId);
229
```
230

231
### Chat Permissions
232

233
Methods for setting default chat permissions.
234

235
```javascript { .api }
236
/**
237
 * Set default chat permissions for all members
238
 * @param {number|string} chatId - Chat identifier
239
 * @param {object} chatPermissions - Default permissions
240
 * @param {object} [options] - Additional options
241
 * @returns {Promise<boolean>}
242
 */
243
setChatPermissions(chatId, chatPermissions, options): Promise<boolean>;
244
```
245

246
**Usage Example:**
247

248
```javascript
249
// Set restrictive default permissions
250
await bot.setChatPermissions(chatId, {
251
  can_send_messages: true,
252
  can_send_audios: false,
253
  can_send_documents: false,
254
  can_send_photos: true,
255
  can_send_videos: true,
256
  can_send_video_notes: false,
257
  can_send_voice_notes: false,
258
  can_send_polls: false,
259
  can_send_other_messages: false,
260
  can_add_web_page_previews: false,
261
  can_change_info: false,
262
  can_invite_users: false,
263
  can_pin_messages: false,
264
  can_manage_topics: false
265
}, {
266
  use_independent_chat_permissions: true
267
});
268
```
269

270
### Chat Settings
271

272
Methods for managing chat appearance and configuration.
273

274
```javascript { .api }
275
/**
276
 * Set chat photo
277
 * @param {number|string} chatId - Chat identifier
278
 * @param {string|Buffer|stream.Readable} photo - Photo to set
279
 * @param {object} [options] - Additional options
280
 * @param {object} [fileOptions] - File upload options
281
 * @returns {Promise<boolean>}
282
 */
283
setChatPhoto(chatId, photo, options, fileOptions): Promise<boolean>;
284

285
/**
286
 * Delete chat photo
287
 * @param {number|string} chatId - Chat identifier
288
 * @param {object} [options] - Additional options
289
 * @returns {Promise<boolean>}
290
 */
291
deleteChatPhoto(chatId, options): Promise<boolean>;
292

293
/**
294
 * Set chat title
295
 * @param {number|string} chatId - Chat identifier
296
 * @param {string} title - New chat title (1-128 characters)
297
 * @param {object} [options] - Additional options
298
 * @returns {Promise<boolean>}
299
 */
300
setChatTitle(chatId, title, options): Promise<boolean>;
301

302
/**
303
 * Set chat description
304
 * @param {number|string} chatId - Chat identifier
305
 * @param {string} description - New description (0-255 characters)
306
 * @param {object} [options] - Additional options
307
 * @returns {Promise<boolean>}
308
 */
309
setChatDescription(chatId, description, options): Promise<boolean>;
310

311
/**
312
 * Set chat sticker set
313
 * @param {number|string} chatId - Chat identifier
314
 * @param {string} stickerSetName - Sticker set name
315
 * @param {object} [options] - Additional options
316
 * @returns {Promise<boolean>}
317
 */
318
setChatStickerSet(chatId, stickerSetName, options): Promise<boolean>;
319

320
/**
321
 * Delete chat sticker set
322
 * @param {number|string} chatId - Chat identifier
323
 * @param {object} [options] - Additional options
324
 * @returns {Promise<boolean>}
325
 */
326
deleteChatStickerSet(chatId, options): Promise<boolean>;
327
```
328

329
**Usage Example:**
330

331
```javascript
332
// Set chat photo
333
await bot.setChatPhoto(chatId, './group-photo.jpg');
334

335
// Set chat title
336
await bot.setChatTitle(chatId, 'New Group Title');
337

338
// Set chat description
339
await bot.setChatDescription(chatId, 'This is the new group description with rules and information.');
340

341
// Set sticker set for supergroup
342
await bot.setChatStickerSet(chatId, 'animals_by_bot');
343

344
// Remove sticker set
345
await bot.deleteChatStickerSet(chatId);
346

347
// Delete chat photo
348
await bot.deleteChatPhoto(chatId);
349
```
350

351
### Message Pinning
352

353
Methods for managing pinned messages in chats.
354

355
```javascript { .api }
356
/**
357
 * Pin chat message
358
 * @param {number|string} chatId - Chat identifier
359
 * @param {number} messageId - Message identifier
360
 * @param {object} [options] - Pin options
361
 * @returns {Promise<boolean>}
362
 */
363
pinChatMessage(chatId, messageId, options): Promise<boolean>;
364

365
/**
366
 * Unpin specific chat message
367
 * @param {number|string} chatId - Chat identifier
368
 * @param {object} [options] - Unpin options
369
 * @returns {Promise<boolean>}
370
 */
371
unpinChatMessage(chatId, options): Promise<boolean>;
372

373
/**
374
 * Unpin all chat messages
375
 * @param {number|string} chatId - Chat identifier
376
 * @param {object} [options] - Additional options
377
 * @returns {Promise<boolean>}
378
 */
379
unpinAllChatMessages(chatId, options): Promise<boolean>;
380
```
381

382
**Usage Example:**
383

384
```javascript
385
// Pin message without notification
386
await bot.pinChatMessage(chatId, messageId, {
387
  disable_notification: true
388
});
389

390
// Pin message with notification
391
await bot.pinChatMessage(chatId, messageId, {
392
  disable_notification: false
393
});
394

395
// Unpin specific message
396
await bot.unpinChatMessage(chatId, {
397
  message_id: messageId
398
});
399

400
// Unpin all messages
401
await bot.unpinAllChatMessages(chatId);
402
```
403

404
### Chat Actions
405

406
Methods for performing various chat-related actions.
407

408
```javascript { .api }
409
/**
410
 * Leave chat
411
 * @param {number|string} chatId - Chat identifier
412
 * @param {object} [options] - Additional options
413
 * @returns {Promise<boolean>}
414
 */
415
leaveChat(chatId, options): Promise<boolean>;
416
```
417

418
**Usage Example:**
419

420
```javascript
421
// Leave a group or channel
422
const left = await bot.leaveChat(chatId);
423
if (left) {
424
  console.log('Successfully left the chat');
425
}
426
```
427

428
### Invite Link Management
429

430
Methods for creating and managing chat invite links.
431

432
```javascript { .api }
433
/**
434
 * Generate new primary invite link
435
 * @param {number|string} chatId - Chat identifier
436
 * @param {object} [options] - Additional options
437
 * @returns {Promise<string>}
438
 */
439
exportChatInviteLink(chatId, options): Promise<string>;
440

441
/**
442
 * Create additional invite link
443
 * @param {number|string} chatId - Chat identifier
444
 * @param {object} [options] - Link options
445
 * @returns {Promise<ChatInviteLink>}
446
 */
447
createChatInviteLink(chatId, options): Promise<ChatInviteLink>;
448

449
/**
450
 * Edit invite link
451
 * @param {number|string} chatId - Chat identifier
452
 * @param {string} inviteLink - Invite link to edit
453
 * @param {object} [options] - New link options
454
 * @returns {Promise<ChatInviteLink>}
455
 */
456
editChatInviteLink(chatId, inviteLink, options): Promise<ChatInviteLink>;
457

458
/**
459
 * Revoke invite link
460
 * @param {number|string} chatId - Chat identifier
461
 * @param {string} inviteLink - Invite link to revoke
462
 * @param {object} [options] - Additional options
463
 * @returns {Promise<ChatInviteLink>}
464
 */
465
revokeChatInviteLink(chatId, inviteLink, options): Promise<ChatInviteLink>;
466
```
467

468
**Usage Example:**
469

470
```javascript
471
// Generate new primary invite link
472
const primaryLink = await bot.exportChatInviteLink(chatId);
473
console.log(`Primary invite link: ${primaryLink}`);
474

475
// Create limited-use invite link
476
const limitedLink = await bot.createChatInviteLink(chatId, {
477
  name: 'Limited Link',
478
  expire_date: Math.floor(Date.now() / 1000) + 86400, // Expires in 24 hours
479
  member_limit: 10, // Max 10 users can join
480
  creates_join_request: false
481
});
482

483
console.log(`Limited link: ${limitedLink.invite_link}`);
484

485
// Create approval-required link
486
const approvalLink = await bot.createChatInviteLink(chatId, {
487
  name: 'Approval Required',
488
  creates_join_request: true
489
});
490

491
// Edit existing link
492
const editedLink = await bot.editChatInviteLink(chatId, limitedLink.invite_link, {
493
  name: 'Updated Limited Link',
494
  member_limit: 5
495
});
496

497
// Revoke link
498
const revokedLink = await bot.revokeChatInviteLink(chatId, limitedLink.invite_link);
499
console.log(`Link revoked: ${revokedLink.is_revoked}`);
500
```
501

502
### Join Request Management
503

504
Methods for handling chat join requests.
505

506
```javascript { .api }
507
/**
508
 * Approve chat join request
509
 * @param {number|string} chatId - Chat identifier
510
 * @param {number} userId - User identifier
511
 * @param {object} [options] - Additional options
512
 * @returns {Promise<boolean>}
513
 */
514
approveChatJoinRequest(chatId, userId, options): Promise<boolean>;
515

516
/**
517
 * Decline chat join request
518
 * @param {number|string} chatId - Chat identifier
519
 * @param {number} userId - User identifier
520
 * @param {object} [options] - Additional options
521
 * @returns {Promise<boolean>}
522
 */
523
declineChatJoinRequest(chatId, userId, options): Promise<boolean>;
524
```
525

526
**Usage Example:**
527

528
```javascript
529
// Handle join requests
530
bot.on('chat_join_request', async (joinRequest) => {
531
  const { chat, from } = joinRequest;
532
  
533
  console.log(`Join request from ${from.first_name} for chat ${chat.title}`);
534
  
535
  // Auto-approve if user has specific criteria
536
  if (from.username && from.username.includes('verified')) {
537
    await bot.approveChatJoinRequest(chat.id, from.id);
538
    console.log(`Approved join request for ${from.first_name}`);
539
  } else {
540
    // For this example, decline others
541
    await bot.declineChatJoinRequest(chat.id, from.id);
542
    console.log(`Declined join request for ${from.first_name}`);
543
  }
544
});
545
```
546

547
## Types
548

549
```javascript { .api }
550
interface Chat {
551
  id: number;
552
  type: 'private' | 'group' | 'supergroup' | 'channel';
553
  title?: string;
554
  username?: string;
555
  first_name?: string;
556
  last_name?: string;
557
  is_forum?: boolean;
558
  photo?: ChatPhoto;
559
  active_usernames?: string[];
560
  available_reactions?: ReactionType[];
561
  accent_color_id?: number;
562
  background_custom_emoji_id?: string;
563
  profile_accent_color_id?: number;
564
  profile_background_custom_emoji_id?: string;
565
  emoji_status_custom_emoji_id?: string;
566
  emoji_status_expiration_date?: number;
567
  bio?: string;
568
  has_private_forwards?: boolean;
569
  has_restricted_voice_and_video_messages?: boolean;
570
  join_to_send_messages?: boolean;
571
  join_by_request?: boolean;
572
  description?: string;
573
  invite_link?: string;
574
  pinned_message?: Message;
575
  permissions?: ChatPermissions;
576
  slow_mode_delay?: number;
577
  unrestrict_boost_count?: number;
578
  message_auto_delete_time?: number;
579
  has_aggressive_anti_spam_enabled?: boolean;
580
  has_hidden_members?: boolean;
581
  has_protected_content?: boolean;
582
  has_visible_history?: boolean;
583
  sticker_set_name?: string;
584
  can_set_sticker_set?: boolean;
585
  custom_emoji_sticker_set_name?: string;
586
  linked_chat_id?: number;
587
  location?: ChatLocation;
588
}
589

590
interface ChatMember {
591
  status: 'creator' | 'administrator' | 'member' | 'restricted' | 'left' | 'kicked';
592
  user: User;
593
  is_anonymous?: boolean;
594
  custom_title?: string;
595
  until_date?: number;
596
}
597

598
interface ChatMemberOwner extends ChatMember {
599
  status: 'creator';
600
  is_anonymous: boolean;
601
  custom_title?: string;
602
}
603

604
interface ChatMemberAdministrator extends ChatMember {
605
  status: 'administrator';
606
  can_be_edited: boolean;
607
  can_manage_chat: boolean;
608
  can_delete_messages: boolean;
609
  can_manage_video_chats: boolean;
610
  can_restrict_members: boolean;
611
  can_promote_members: boolean;
612
  can_change_info: boolean;
613
  can_invite_users: boolean;
614
  can_post_messages?: boolean;
615
  can_edit_messages?: boolean;
616
  can_pin_messages?: boolean;
617
  can_post_stories?: boolean;
618
  can_edit_stories?: boolean;
619
  can_delete_stories?: boolean;
620
  can_manage_topics?: boolean;
621
  custom_title?: string;
622
  is_anonymous: boolean;
623
}
624

625
interface ChatMemberMember extends ChatMember {
626
  status: 'member';
627
}
628

629
interface ChatMemberRestricted extends ChatMember {
630
  status: 'restricted';
631
  is_member: boolean;
632
  can_send_messages: boolean;
633
  can_send_audios: boolean;
634
  can_send_documents: boolean;
635
  can_send_photos: boolean;
636
  can_send_videos: boolean;
637
  can_send_video_notes: boolean;
638
  can_send_voice_notes: boolean;
639
  can_send_polls: boolean;
640
  can_send_other_messages: boolean;
641
  can_add_web_page_previews: boolean;
642
  can_change_info: boolean;
643
  can_invite_users: boolean;
644
  can_pin_messages: boolean;
645
  can_manage_topics: boolean;
646
  until_date: number;
647
}
648

649
interface ChatMemberLeft extends ChatMember {
650
  status: 'left';
651
}
652

653
interface ChatMemberBanned extends ChatMember {
654
  status: 'kicked';
655
  until_date: number;
656
}
657

658
interface ChatPermissions {
659
  can_send_messages?: boolean;
660
  can_send_audios?: boolean;
661
  can_send_documents?: boolean;
662
  can_send_photos?: boolean;
663
  can_send_videos?: boolean;
664
  can_send_video_notes?: boolean;
665
  can_send_voice_notes?: boolean;
666
  can_send_polls?: boolean;
667
  can_send_other_messages?: boolean;
668
  can_add_web_page_previews?: boolean;
669
  can_change_info?: boolean;
670
  can_invite_users?: boolean;
671
  can_pin_messages?: boolean;
672
  can_manage_topics?: boolean;
673
}
674

675
interface ChatInviteLink {
676
  invite_link: string;
677
  creator: User;
678
  creates_join_request: boolean;
679
  is_primary: boolean;
680
  is_revoked: boolean;
681
  name?: string;
682
  expire_date?: number;
683
  member_limit?: number;
684
  pending_join_request_count?: number;
685
}
686

687
interface ChatJoinRequest {
688
  chat: Chat;
689
  from: User;
690
  user_chat_id: number;
691
  date: number;
692
  bio?: string;
693
  invite_link?: ChatInviteLink;
694
}
695
```