BanChatMember
BanChatMember — блокирует пользователя в чате/канале.
📝 Назначение
Используется для модерации: блокировка нарушителей, автоматические баны по условиям, временная изоляция пользователя.
Эффект от блокировки:
- Пользователь не может отправлять сообщения
- Пользователь не может просматривать историю чата (если настроено соответствующим образом)
- При указании
revoke_messages— все сообщения пользователя удаляются
💡 Совет: Для снятия блокировки используйте реакцию UnBanChatMember.
⚙️ Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| chat_id | Integer/String | ✅ Да | ID чата или @username канала |
| user_id | Integer | ✅ Да | ID пользователя для блокировки |
| until_date | Integer | ❌ Нет | Время снятия блокировки (Unix timestamp). По умолчанию — 0 (бессрочно) |
| revoke_messages | Boolean | ❌ Нет | Удалить ли все сообщения пользователя. По умолчанию — false |
📅 Формат until_date
Параметр until_date принимает Unix timestamp (количество секунд с 1 января 1970 года).
Как получить значение:
| Способ | Пример | Результат |
|---|---|---|
Макрос !{time} |
`!{time | value:now; plus:1d; output_format:unix}` |
Макрос !{time} |
`!{time | value:now; plus:2h; output_format:unix}` |
Макрос !{time} |
`!{time | value:now; plus:30m; output_format:unix}` |
| Вручную | 1748880000 |
Конкретная дата |
💡 Совет: Если
until_dateменьше текущего времени или равен0, блокировка считается бессрочной.
🔐 Требуемые права бота
| Право | Описание |
|---|---|
| Администратор чата | Бот должен быть администратором чата |
| can_restrict_members | Право блокировать участников (обязательно) |
💡 Совет: Проверить права бота можно через реакцию
GetChatMemberдля самого бота или в разделе/adm→ Чаты/Каналы.
🧪 Примеры использования
Пример 1: Бессрочная блокировка с удалением сообщений
Задача: Забанить пользователя навсегда и удалить все его сообщения.
Параметры BanChatMember:
chat_id:${chat.id}user_id:${user.id}revoke_messages:true
Пример 2: Временная блокировка на 1 час
Задача: Забанить пользователя на 1 час без удаления сообщений.
Параметры BanChatMember:
chat_id:${chat.id}user_id:${user.id}until_date:!{time|value:now; plus:1h; output_format:unix}
Пример 3: Блокировка на 7 дней с удалением сообщений
Задача: Забанить пользователя на неделю и удалить все его сообщения.
Параметры BanChatMember:
chat_id:${chat.id}user_id:${user.id}until_date:!{time|value:now; plus:7d; output_format:unix}revoke_messages:true
Пример 4: Блокировка другого пользователя (администратор)
Задача: Администратор наказывает пользователя по команде /ban @username 2h.
Параметры BanChatMember:
chat_id:${chat.id}user_id:${target_user.id}(извлечён из команды черезTakeUser)until_date:!{time|value:now; plus:2h; output_format:unix}
🔄 Особенности поведения
| Ситуация | Поведение |
|---|---|
| Блокировка пользователя, которого уже нет в чате | Пользователь будет заблокирован, но не сможет вернуться до снятия блокировки |
| Блокировка владельца чата | Невозможна. Telegram не позволяет забанить создателя чата |
| Блокировка администратора другим администратором | Возможно только если у бота есть право can_restrict_members и уровень прав достаточен |
| Блокировка бота | Невозможна (Telegram запрещает) |
🔗 Связанные реакции
| Реакция | Назначение |
|---|---|
| UnBanChatMember | Снять блокировку |
| RestrictChatMember | Ограничить, но не блокировать |
| BanBotUser | Заблокировать пользователя в боте (не в чате) |
🔗 Связанные разделы
| Раздел | Описание |
|---|---|
| Обработчики «Вход/выход» | Отслеживание банов |
| Макрос time | Генерация until_date |
🔗 Быстрая навигация
- Вверх
- Параметры
- Формат until_date
- Требуемые права
- Примеры
- Особенности
- Частые ошибки