Перейти к содержанию
11 минут чтения
Тема: Практика Telegram Bot API · Заявки · Права доступа

Как обрабатывать заявки на вступление в Telegram-группу или канал через бота

Для примера учебный центр принимает участников в закрытую группу курса. Бот получает заявку, находит ученика в своей базе и показывает администратору кнопки решения. Разберём, как сохранить заявку, проверить право на доступ и не выполнить старое решение повторно. Та же схема подходит для закрытого канала.

Готовим права и ссылку с заявкой

Добавьте бота администратором целевой группы или канала с правом can_invite_users. В этом руководстве используется обычный бот-администратор и стандартное событие chat_join_request. Специальный режим ботов, назначенных только для обработки заявок, здесь не рассматривается.

Для примера создадим отдельную ссылку через createChatInviteLink. Следующий JSON — параметры одного вызова метода вашим настроенным Telegram API-клиентом; это не файл настроек webhook.

JSON · createChatInviteLink
{
  "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 для проверки доступа не нужно.

JSON · Входящее событие
{
  "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 должен находиться вне публичного каталога сайта.

SQL · Таблица входящих заявок
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 · Сохранение одной заявки
<?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; при ошибке проверки отказывайте в выполнении действия.

Два администратора могут нажать одновременно. После проверки полномочий попробуйте атомарно занять заявку. Это пример условного перехода состояния; параметры заполняет ваш обработчик.

SQL · Только один обработчик получает право выполнить действие
UPDATE join_requests
SET state = 'processing', decision = :decision
WHERE id = :id AND bot_id = :bot_id AND state = 'pending';

Продолжайте только при изменении одной строки. Решение допускает два значения: approve и decline. После фиксации перехода вызовите соответственно approveChatJoinRequest или declineChatJoinRequest с одинаковой парой параметров:

JSON · Параметры одобрения или отклонения
{
  "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 не используется.

Локальная дедупликация и проверка полномочий всё равно нужны: повтор может возникнуть внутри приложения или при повторном нажатии. Шлюз не знает, кто оплатил курс и какой администратор вправе принять решение.

Официальная документация