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, коли з вхідними дверима розберетеся.