Telegram Guardian Bot: как настроить проверку заявок на вступление

Telegram Guardian Bot: как настроить проверку заявок на вступление

Коротко. Bot API 10.1, выпущенный 11 июня 2026 года, добавил роль "Guardian Bot" — отдельного бота, которому канал или группа могут доверить проверку заявок на вступление. Guard-бот получает обновления ChatJoinRequest с полем query_id, принимает решение и отвечает через новый метод answerChatJoinRequestQuery, а при необходимости сначала показывает заявителю мини-приложение через sendChatJoinRequestWebApp. В этом гайде — что именно изменилось, как эти части работают вместе и как собрать сценарий проверки, не переписывая всё с нуля.

Хотите, чтобы проверка заявок работала рядом с расписанием публикаций, а не как отдельный проект? Посмотрите, как слой автоматизации Autogram обрабатывает события канала.

Что понадобится

• Telegram-канал или группа с включённым одобрением новых участников (join requests).
• Бот, созданный через @BotFather, добавленный как администратор с правом управлять заявками на вступление.
• Базовое понимание Bot API (вебхук или getUpdates) — этот гайд предполагает, что вы уже получаете обновления.
• Опционально: Web App (HTTPS-страница), если хотите проверять заявителей через sendChatJoinRequestWebApp, а не просто одобрять или отклонять.

Шаг 1 — что именно добавил Bot API 10.1 для Guardian Bot

До Bot API 10.1 бот, обрабатывающий заявки на вступление, работал с объектом ChatJoinRequest и единственным методом answerChatJoinRequest(chat_id, user_id, approved) — простым "принять или отклонить". Чейнджлог от 11 июня 2026 года добавил поверх этого концепцию "запроса":

• ChatJoinRequest.query_id — новое опциональное поле, которое идентифицирует конкретную заявку на вступление как запрос, на который бот может ответить.
• answerChatJoinRequestQuery(chat_id, user_id, query_id, approved, invite_link?) — новый метод, построенный вокруг этого идентификатора. Он так же одобряет или отклоняет заявку, но привязывает ответ к конкретному запросу, а не только к user_id.
• User.supports_join_request_queries — флаг в ответе собственного getMe бота: "да, меня можно назначить обрабатывать такие запросы".
• ChatFullInfo.guard_bot — поле, видимое только администраторам чата, которое показывает, какой бот сейчас проверяет заявки на вступление в этом чате.

Официальное объявление Telegram описывает функцию просто: "добавьте AI-ботов как администраторов для обработки заявок на вступление" — и добавляет, что они "могут также карать неправедных, кто пишет в чате, если вы этого хотите". Вторая часть важна: работа guard-бота не заканчивается на входе. Тот же бот может оставаться и модерировать контент после принятия, если вы дадите ему соответствующие права.

Шаг 2 — назначьте своего Telegram Guardian Bot

Отдельного API-вызова "назначить guardian" в Bot API 10.1 нет — назначение работает так же, как всегда работали права администратора бота: добавьте бота в чат и дайте ему право управлять заявками на вступление. После этого, когда ответ бота на getMe покажет supports_join_request_queries: true, Telegram считает его guard-ботом чата — это отражается администраторам как ChatFullInfo.guard_bot.

Две вещи стоит проверить перед тем, как полагаться на это в проде:

1. Проверьте флаг. Вызовите getMe и проверьте supports_join_request_queries. Если ваша библиотека устарела для Bot API 10.1 — обновите её: более старые версии просто не покажут это поле.
2. Проверьте право администратора. Боту нужно именно право "управлять заявками на вступление". Статуса администратора недостаточно, если это право не было отмечено при добавлении бота.

Шаг 3 — обработайте запрос и дайте ответ

Когда кто-то подаёт заявку на вступление, ваш бот получает обновление chat_join_request с объектом ChatJoinRequest, теперь уже с заполненным query_id. Дальше есть два пути.

Прямое решение. Если у вас уже достаточно сигналов — список разрешённых, предыдущее взаимодействие, совпадение ключевого слова в био — сразу вызовите answerChatJoinRequestQuery, передав chat_id, user_id, query_id из обновления и approved. Добавьте invite_link, если чат приватный и вы хотите дать одобренному пользователю рабочую ссылку.

Сначала проверка, потом решение. Если хотите, чтобы заявитель ответил на вопрос или согласился с правилами перед вступлением, вызовите sendChatJoinRequestWebApp(chat_id, app_url, button_text?), чтобы показать ему Web App — вашу собственную HTTPS-страницу. Заявитель проходит сценарий, который вы построили (короткий тест, подтверждение правил, проверку домена почты), а ваш бэкенд вызывает answerChatJoinRequestQuery, когда получит ответ.

Именно такой двухэтапный подход — сначала проверка, потом решение — описывают первые обзоры после запуска в июне 2026 года: он разделяет обнаружение и принятие решения, поэтому ошибочный отказ не требует полной процедуры апелляции — достаточно новой заявки.

Типичные ошибки

• Считать, что chat_id и user_id достаточно. answerChatJoinRequestQuery в Bot API 10.1 требует ещё и query_id. Код, написанный под старый метод answerChatJoinRequest, не соберётся против новой сигнатуры — проверьте чейнджлог вашей библиотеки, прежде чем предполагать совместимость.
• Воспринимать guard_bot как ответ по конкретной заявке. guard_bot показывает, какой бот сейчас обрабатывает запросы чата, но не результат конкретной заявки. Ведите собственный журнал решений, если нужен аудит: Telegram не хранит его за вас, кроме журнала администратора самого чата.
• Пропускать мини-приложение и строить диалог в чате вручную. sendChatJoinRequestWebApp существует именно для того, чтобы проверка не превращалась в неудобный обмен сообщениями в приватном чате. Web App даёт настоящую форму — и это паттерн, который официальное объявление Telegram выделяет первым.
• Давать права модерации без политики. Guard-бот, который ещё и удаляет сообщения, — мощный инструмент. Определите заранее, что именно запускает удаление, иначе придётся разбираться с ложными срабатываниями уже после того, как их заметили участники.

Что ещё почитать

• Telegram Bot API 10.0: гостевой режим для владельцев каналов — релиз непосредственно перед этим, о гостевых ответах и обмене сообщениями бот-бот.
• Telegram Super Channels: Руководство для мультиавторского канала — для команд, которые управляют тем, кто публикует, а не только тем, кто вступает.
• Telegram Managed Bots: что известно до апрельского запуска — боты на хостинге платформы, смежное изменение в том, сколько инфраструктуры нужно для автоматизации канала.

FAQ

Что такое Telegram Guardian Bot?

Guardian Bot — это бот, которого администраторы чата назначают обрабатывать заявки на вступление, а опционально — и модерировать сообщения после принятия. Это не новый тип бота, а роль, которую может взять на себя ваш существующий бот, если он поддерживает запросы на вступление из Bot API 10.1.

Обязателен ли Bot API 10.1 для этого?

Да. Поле query_id в ChatJoinRequest, метод answerChatJoinRequestQuery, sendChatJoinRequestWebApp, а также поля guard_bot и supports_join_request_queries появились именно в Bot API 10.1, выпущенном 11 июня 2026 года. Более старые версии библиотек их не покажут.

Чем это отличается от старого метода answerChatJoinRequest?

Метод до версии 10.1 принимал только chat_id, user_id и approved — простое "принять или отклонить". Новый подход с запросами привязывает ответ к конкретному query_id и сочетается с sendChatJoinRequestWebApp, чтобы можно было сначала проверить, а не сразу решать.

Может ли Guardian Bot отклонить заявку, а человек — попробовать снова?

Да. Отклонение заявки не блокирует пользователя. Он может подать новую заявку, и ваш бот получит новый запрос с новым query_id.

Обязательно ли guard-бот должен быть тем же ботом, что публикует контент?

Нет. Bot API 10.1 этого не требует. Многие операторы запускают отдельного бота для проверки с более узкими правами, чем основной бот публикации или автоматизации — это снижает последствия, если в логике проверки есть ошибка.

Могу ли я увидеть, какой бот сейчас охраняет мой чат?

Да, если вы администратор чата: поле ChatFullInfo.guard_bot указывает на него. Поле доступно только администраторам — обычные участники и публика его не видят.

Что будет, если я не построю сценарий проверки — заявки на вступление всё равно будут работать?

Да. Bot API 10.1 ничего не убирает из старого поведения одобрения или отклонения. Guardian Bot — это дополнение: чат без назначенного guard-бота ведёт себя точно так же, как раньше.

Может ли один и тот же бот и проверять новых участников, и модерировать существующих?

Да, если вы дадите ему соответствующие права администратора вместе с управлением заявками на вступление. Официальное объявление Telegram прямо описывает это как часть одной функции, а не отдельную.

Итог

Bot API 10.1 превращает вопрос "кого впускать" из бинарного "принять или отклонить" в настоящий конвейер — сначала проверка, потом решение — и для этого не нужно строить диалоговый сценарий бота с нуля. Если ваш канал уже получает больше заявок на вступление, чем вы успеваете проверить вручную, самое время это настроить. Автоматизируйте остальную работу канала вместе с Autogram, когда с входной дверью разберётесь.