Готовим права и ссылку с заявкой
Добавьте бота администратором целевой группы или канала с правом can_invite_users. В этом руководстве используется обычный бот-администратор и стандартное событие chat_join_request. Специальный режим ботов, назначенных только для обработки заявок, здесь не рассматривается.
Для примера создадим отдельную ссылку через createChatInviteLink. Следующий JSON — параметры одного вызова метода вашим настроенным Telegram API-клиентом; это не файл настроек webhook.
{
"chat_id": -1001234567890,
"name": "Учебная группа",
"creates_join_request": true
}
Сохраните invite_link из успешного ответа. Проверьте переход по нему с тестового аккаунта, который ещё не состоит в группе: должна появиться заявка, а не немедленное вступление. При creates_join_request=true не передавайте member_limit. Бот управляет собственными приглашениями; ссылку другого администратора не следует считать своей.
Если остаются другие ссылки с прямым входом, люди могут попадать в сообщество в обход этого сценария. Проверьте все действующие способы вступления до того, как связывать доступ с оплатой или обучением.
Получаем и сохраняем chat_join_request
В allowed_updates действующего webhook включите chat_join_request и callback_query, сохранив остальные нужные типы. Не удаляйте webhook и не очищайте ожидающие обновления ради этой настройки. Если событие не приходит, сначала проверьте права бота и доставку webhook.
Сокращённый пример update выглядит так. ID и даты вымышлены; подставлять этот JSON в рабочий webhook для проверки доступа не нужно.
{
"update_id": 850001,
"chat_join_request": {
"chat": {"id": -1001234567890, "type": "supergroup", "title": "Курс"},
"from": {"id": 123456789, "is_bot": false, "first_name": "Анна"},
"user_chat_id": 987654321,
"date": 1793782800
}
}
chat.id — сообщество, from.id — заявитель. Именно from.id передавайте как user_id при решении. user_chat_id предназначен для ограниченного по времени личного контакта и не заменяет user_id. Telegram допускает такой контакт в течение пяти минут, пока заявка не обработана и при условии, что другой администратор ещё не связался с пользователем. На длительную переписку по этому ID рассчитывать нельзя.
Ниже — функция сохранения для PHP 8.3+ и PDO SQLite. Её вызывают из уже настроенного обработчика после проверки подлинности webhook. Передайте внутренний идентификатор бота и декодированный update. Это компонент обработчика, а не готовый публичный endpoint. Файл SQLite должен находиться вне публичного каталога сайта.
CREATE TABLE join_requests (
id INTEGER PRIMARY KEY AUTOINCREMENT,
bot_id TEXT NOT NULL,
update_id INTEGER NOT NULL,
chat_id INTEGER NOT NULL,
user_id INTEGER NOT NULL,
requested_at INTEGER NOT NULL,
state TEXT NOT NULL DEFAULT 'pending',
decision TEXT,
UNIQUE (bot_id, update_id)
);
<?php
declare(strict_types=1);
function saveJoinRequest(PDO $db, string $botId, array $update): bool
{
$request = $update['chat_join_request'] ?? null;
if (!is_array($request)) {
return false;
}
foreach ([$update['update_id'] ?? null, $request['chat']['id'] ?? null,
$request['from']['id'] ?? null, $request['date'] ?? null] as $value) {
if (!is_int($value)) {
throw new InvalidArgumentException('Invalid update');
}
}
$query = $db->prepare('INSERT INTO join_requests
(bot_id, update_id, chat_id, user_id, requested_at)
VALUES (?, ?, ?, ?, ?)
ON CONFLICT(bot_id, update_id) DO NOTHING');
$query->execute([$botId, $update['update_id'], $request['chat']['id'],
$request['from']['id'], $request['date']]);
return $query->rowCount() === 1;
}
Один и тот же update одного бота создаёт одну запись. Новая заявка того же человека должна сохраняться отдельно: постоянный UNIQUE по паре chat_id/user_id помешал бы повторному обращению после отказа. Запускайте дальнейшую обработку по сохранённым pending-записям: если процесс упадёт после INSERT, отдельный worker всё равно найдёт заявку. Если вставка не удалась, не подтверждайте webhook успешным ответом.
Проверяем условия доступа по своей базе
Для нашего курса условие — действующая запись на конкретный поток. Связь ученика с Telegram ID должна быть подтверждена заранее: например, через привязку аккаунта сайта. Имя, username, bio и название приглашения не доказывают оплату и не заменяют эту связь.
Полезно разделить результаты проверки:
Доступ подтверждён: найдена активная запись, совпадает поток, срок ещё действует.
Условие не выполнено: запись отсутствует или доступ закончился; администратор видит конкретную причину.
Проверка недоступна: база или CRM не ответила. Заявка остаётся на рассмотрении, временный сбой не превращается в автоматический отказ.
Покажите оператору сообщество, ID заявителя, дату заявки и найденное основание доступа. Пользовательский текст выводите без parse_mode либо экранируйте под выбранную разметку. Не пересылайте в общий чат платёжные реквизиты и лишние персональные данные.
Если требуется подписка на другой канал, используйте отдельную проверку членства. Заявка на вступление ещё не означает, что человек уже стал участником целевого сообщества.
Принимаем решение администратора
В callback_data кнопки храните короткий внутренний ID заявки и действие, например join:42:approve. chat_id и user_id для вызова Telegram извлекайте из БД. На нажатие отвечайте answerCallbackQuery, а полномочия проверяйте по callback_query.from.id и актуальной роли сотрудника на сервере.
Наличие кнопки или доступ к сообщению не даёт права одобрять людей. Проверяйте также, что заявка принадлежит этому боту и разрешённому сообществу. Если решение доверено администраторам самого Telegram-чата, проверяйте их текущий статус через getChatMember; при ошибке проверки отказывайте в выполнении действия.
Два администратора могут нажать одновременно. После проверки полномочий попробуйте атомарно занять заявку. Это пример условного перехода состояния; параметры заполняет ваш обработчик.
UPDATE join_requests SET state = 'processing', decision = :decision WHERE id = :id AND bot_id = :bot_id AND state = 'pending';
Продолжайте только при изменении одной строки. Решение допускает два значения: approve и decline. После фиксации перехода вызовите соответственно approveChatJoinRequest или declineChatJoinRequest с одинаковой парой параметров:
{
"chat_id": -1001234567890,
"user_id": 123456789
}
Успешный ответ имеет ok=true и result=true. Только после него сохраните approved или declined и уберите кнопки из сообщения администратора. Отказ в заявке сам по себе не является баном участника. Если условия изменились между предварительной проверкой и нажатием, ещё раз проверьте их перед одобрением.
Различаем дубликат, новую заявку и неизвестный результат
Повторная доставка update и повторное нажатие — разные вещи. Первую ограничивает UNIQUE(bot_id, update_id), вторую — условный переход из pending. Записывайте ID администратора и время решения для разбора спорных случаев; при необходимости расширьте приведённую учебную таблицу.
Перед обработкой кнопки убедитесь, что для этого человека не сохранена более новая заявка в том же сообществе. Старую пометьте superseded. Это защищает от уже известных устаревших событий, но не создаёт полной атомарности с Telegram: методы решения принимают chat_id/user_id, без отдельного ID заявки. Новая заявка может возникнуть между вашей проверкой и API-вызовом. Сериализация работы по паре бот/чат/пользователь и короткое время жизни кнопок уменьшают риск; абсолютную гарантию для конкретного поколения заявки эти методы не дают.
При таймауте после API-вызова сохраните unknown, а не возвращайте запись в pending. Возможно, Telegram уже выполнил решение. getChatMember поможет понять, вступил ли пользователь, но статус left не различает отклонённую, отозванную и ещё ожидающую заявку. Если другой администратор обработал её вручную, локальная запись также может устареть. Для таких случаев предусмотрите сверку и ручное завершение, а не бесконечный повтор.
Если worker упал в состоянии processing, считайте исход потенциально неизвестным и разбирайте его отдельно. Надёжная запись в БД и запрос к Telegram не являются одной транзакцией. Подробности этой границы разобраны в статье о повторной обработке событий.
Проверяем сценарий на тестовой группе
Подайте заявку с аккаунта без записи на курс: событие сохранится, но доступ не будет одобрен автоматически.
Подайте заявку с подтверждённой записью: оператор увидит основание и сможет одобрить вступление.
Дважды передайте одинаковый update функции сохранения: в таблице останется одна строка.
Дважды нажмите решение: второй обработчик не должен вызвать API повторно.
Отзовите роль сотрудника перед нажатием: действие должно быть запрещено независимо от видимости кнопки.
Смоделируйте потерю ответа Telegram: заявка перейдёт в разбор неизвестного исхода, а не в цикл повторов.
Если webhook и запросы идут через BotGate
Для исходящих методов используются те же chat_id, user_id и права Telegram. Входящие webhook BotGate проверяются по схеме подписи сервиса, описанной в документации; не подменяйте её проверкой заголовка прямого webhook Telegram. getUpdates через BotGate не используется.
Локальная дедупликация и проверка полномочий всё равно нужны: повтор может возникнуть внутри приложения или при повторном нажатии. Шлюз не знает, кто оплатил курс и какой администратор вправе принять решение.
Официальная документация
ChatJoinRequest — поля события и временный контакт с заявителем.
createChatInviteLink — создание ссылки с заявкой.
approveChatJoinRequest и declineChatJoinRequest — решение по заявке.