Обработчики «Вход/выход»

Что это такое

Обработчики «Вход/выход» отслеживают изменения статуса пользователей и бота в чатах, а также запросы на вступление. Они позволяют автоматизировать действия при вступлении нового участника, выходе, назначении администратора, блокировке бота пользователем и других событиях.

Важно: Для большинства событий этого типа бот должен быть администратором чата (группы, супергруппы или канала).

Доступные типы

Тип	Событие	Когда срабатывает	Требует прав админа
chat_member	Изменение статуса любого участника	Вход, выход, бан, разбан, назначение администратора, выдача ограничений	✅ Да
my_chat_member	Изменение статуса самого бота	Бота добавили/удалили из чата, изменили права, пользователь заблокировал/разблокировал бота	❌ Нет (для личных чатов) / ✅ Да (для групп)
chat_join_request	Запрос на вступление	Пользователь отправил заявку в чат с режимом одобрения	✅ Да (право can_invite_users)

chat_member

Описание

Обработчик chat_member срабатывает, когда статус любого участника чата (кроме самого бота) изменяется. Это наиболее универсальный тип для отслеживания действий пользователей в группах и каналах.

Возможные статусы

Статус участника может принимать следующие значения:

Статус	Описание
creator	Владелец чата (создатель)
administrator	Администратор чата
member	Обычный участник
restricted	Участник с ограничениями (тайм-аут)
left	Покинул чат (вышел самостоятельно)
kicked	Исключён из чата (забанен администратором)

Когда срабатывает

Пользователь вошёл в чат (через ссылку, поиск или приглашение)
Пользователь вышел из чата
Администратор заблокировал пользователя (статус kicked)
Администратор разблокировал пользователя (статус member или left → member)
Администратор назначил другого администратора
Администратор лишил прав администратора
Администратор выдал ограничения (статус restricted)
Администратор снял ограничения

Поля в контексте

При срабатывании обработчика в переменных становятся доступны следующие данные:

Переменная	Описание
`${update.chat_member.old_chat_member.status}`	Статус участника до изменения
`${update.chat_member.new_chat_member.status}`	Статус участника после изменения
`${update.chat_member.from.id}`	ID пользователя, который выполнил действие (например, администратор, выдавший бан)
`${update.chat_member.from.first_name}`	Имя инициатора действия
`${update.chat_member.from.username}`	Username инициатора
`${update.chat_member.chat.id}`	ID чата, в котором произошло событие
`${update.chat_member.chat.title}`	Название чата
`${update.chat_member.new_chat_member.user.id}`	ID пользователя, чей статус изменился
`${update.chat_member.new_chat_member.user.first_name}`	Имя этого пользователя
`${update.chat_member.new_chat_member.user.username}`	Его username

my_chat_member

Описание

Обработчик my_chat_member срабатывает, когда меняется статус самого бота в чате или личном диалоге. Это ключевой тип для автоматической настройки бота при добавлении в группы.

Когда срабатывает

В группах и каналах:

Бота добавили в чат (статус left → member или administrator)
Бота удалили из чата (статус member → left)
Боту выдали права администратора (статус member → administrator)
Бота лишили прав администратора (статус administrator → member)

В личных чатах:

Пользователь заблокировал бота (статус member → kicked)
Пользователь разблокировал бота (статус kicked → member)

Особенности

Для отслеживания событий в личных чатах не требуется быть администратором — это работает всегда.
Для групп и каналов бот должен быть участником чата (хотя бы с минимальными правами).

Поля в контексте

Переменная	Описание
`${update.my_chat_member.old_chat_member.status}`	Предыдущий статус бота
`${update.my_chat_member.new_chat_member.status}`	Новый статус бота
`${update.my_chat_member.chat.id}`	ID чата
`${update.my_chat_member.chat.title}`	Название чата (для групп)
`${update.my_chat_member.from.id}`	Кто выполнил действие (пользователь или администратор)
`${update.my_chat_member.from.first_name}`	Имя инициатора
`${update.my_chat_member.new_chat_member.user.id}`	ID бота (полезно для проверок)

chat_join_request

Описание

Обработчик chat_join_request срабатывает, когда пользователь отправляет запрос на вступление в чат, где включён режим одобрения заявок (Join by Request). В отличие от обычного входа (когда пользователь входит по ссылке), здесь требуется ручное или автоматическое одобрение.

Требования

Бот должен быть администратором чата
бота должно быть право can_invite_users (приглашать пользователей)
В чате (супергруппе) должен быть включён режим «Одобрение заявок» (Join by Request)

Как узнать, включён ли режим одобрения

Режим одобрения включён, если в настройках группы (или канала) стоит опция: пользователи могут вступать только после одобрения администратором (или ботом). В Telegram это настраивается в разделе «Тип группы» → «Ограниченная группа» → «Требуется одобрение».

Поля в контексте

Переменная	Описание
`${update.chat_join_request.chat.id}`	ID чата, куда запрашивается вступление
`${update.chat_join_request.chat.title}`	Название чата
`${update.chat_join_request.from.id}`	ID пользователя, который запрашивает вступление
`${update.chat_join_request.from.first_name}`	Имя пользователя
`${update.chat_join_request.from.last_name}`	Фамилия (если есть)
`${update.chat_join_request.from.username}`	Username (если есть)
`${update.chat_join_request.date}`	Дата запроса (Unix time)
`${update.chat_join_request.bio}`	Био пользователя (если заполнено)
`${update.chat_join_request.invite_link}`	Ссылка-приглашение, через которую пользователь подал заявку (если применимо)

Действия с заявкой

После срабатывания обработчика вы можете одобрить или отклонить заявку с помощью специальных реакций:

Реакция	Действие
ApproveChatJoinRequest	Одобрить заявку, пользователь вступает в чат
DeclineChatJoinRequest	Отклонить заявку, пользователь не вступает

Важно: Эти реакции требуют тех же прав, что и обработчик: бот должен быть администратором с правом can_invite_users.

Сравнительная таблица

Характеристика	chat_member	my_chat_member	chat_join_request
Что отслеживает	Статус любого участника	Статус бота	Запросы на вступление
Требует прав админа	✅ Да	❌ Нет (в ЛС) / ✅ Да (в группах)	✅ Да (can_invite_users)
Срабатывает при блокировке бота	❌ Нет	✅ Да	❌ Нет
Можно автоматически одобрить заявку	❌ Нет	❌ Нет	✅ Да
Доступные статусы	creator, admin, member, restricted, left, kicked	member, administrator, left, kicked (нет статусов)
Где работает	Супергруппы, каналы Супергруппы, каналы, личные чаты	Супергруппы (с режимом одобрения)

Резюме

Тип	Основное применение	Сложность настройки
chat_member	Приветствия, уведомления о выходе, логирование банов и ограничений	Средняя
my_chat_member	Автонастройка бота при добавлении в группы, очистка данных при блокировке	Низкая
chat_join_request	Модерация входящих заявок (автоодобрение или автоотклонение)	Средняя / Высокая