Перейти к содержанию
11 минут чтения
Тема: Практика Telegram Bot API · Каналы · PHP

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

Для примера бот выдаёт учебный материал подписчикам канала. Пользователь открывает канал, подписывается и нажимает «Проверить» в личном чате. Приложение должно проверить именно нажавшего пользователя и отличить отсутствие подписки от временной ошибки Telegram.

Готовим канал и права бота

Метод getChatMember возвращает данные одного участника по chat_id и user_id. Telegram гарантирует работу метода для других пользователей, когда бот является администратором соответствующего чата. Поэтому сначала добавьте бота администратором своего канала и проверьте его доступ.

Для публичного канала chat_id можно задать как @channel_username; для приватного используйте числовой ID. Ссылка-приглашение вида t.me/+… не заменяет chat_id. Храните целевой канал в конфигурации сервера, отдельно от ссылки, которую покажете человеку.

Нажатие URL-кнопки «Открыть канал» не доказывает подписку. Бот не получает от этой кнопки подтверждения вступления. Ссылка с заявкой на вступление тоже не означает, что пользователь уже принят. Проверка нужна после фактического вступления.

Для первой диагностики выполните getChatMember для собственного тестового аккаунта, сначала подписанного на канал, затем вышедшего из него. При ошибке проверьте ID канала, права и ID пользователя; не выдавайте любую ошибку за «Вы не подписаны».

Вызываем getChatMember напрямую

Пример Bash требует заранее заданных переменных TELEGRAM_BOT_TOKEN, CHANNEL_ID и TELEGRAM_USER_ID. Он ничего не публикует и не меняет подписку, а только читает состояние участника. Не сохраняйте токен и полный URL в журналах.

Bash · проверка участника
curl --silent --show-error --max-time 15 \
  --request POST \
  "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChatMember" \
  --data-urlencode "chat_id=$CHANNEL_ID" \
  --data-urlencode "user_id=$TELEGRAM_USER_ID"

Успешный ответ содержит ok: true и result со status и user. Для принятия решения нужны три результата: yes — состоит в канале, no — не состоит, unknown — проверить не удалось. Ошибку сети, ok: false и неожиданный формат оставляем в unknown.

  • creator, administrator, member → yes. Владелец и администратор тоже являются участниками.

  • left, kicked → no.

  • restricted → проверяем is_member. Этот тип относится к супергруппам; обработка полезна, если позже тот же код применят к группе.

  • Отсутствующий или неизвестный status, неправильный user.id → unknown.

Не используйте условие status !== left: оно ошибочно пропустит kicked и неизвестные состояния. Для restricted отсутствие is_member тоже нельзя считать успешной проверкой.

Разбираем результат в PHP

Следующая функция принимает именно объект result, а не весь HTTP-ответ. Она дополнительно сверяет пользователя, чтобы случайно не принять ответ из неверного кэша. Требуется 64-битный PHP 8.2+.

PHP · membership.php
<?php
declare(strict_types=1);

function membershipStatus(array $member, int $expectedUserId): string
{
    if (($member['user']['id'] ?? null) !== $expectedUserId) {
        return 'unknown';
    }
    return match ($member['status'] ?? null) {
        'creator', 'administrator', 'member' => 'yes',
        'left', 'kicked' => 'no',
        'restricted' => match ($member['is_member'] ?? null) {
            true => 'yes',
            false => 'no',
            default => 'unknown',
        },
        default => 'unknown',
    };
}

Для yes откройте доступ в своём приложении, для no предложите вступить и повторить проверку, для unknown покажите «Не удалось проверить подписку. Попробуйте позже». В журнале сохраняйте техническую причину отдельно от решения о доступе, без токенов и полного входящего тела.

Результат — состояние на момент запроса. Человек может выйти из канала позже. Для действия, которому нужна текущая подписка, проверяйте её перед действием; короткий кэш должен иметь ключ bot_id + channel_id + user_id и явный срок жизни. Не превращайте единственный успешный ответ в бессрочное право.

Добавляем кнопки и проверяем отправителя

Отправьте пользователю сообщение с двумя inline-кнопками. Замените example_channel своим публичным каналом; для приватного укажите действующую пригласительную ссылку, которую вы вправе раскрыть этому пользователю.

JSON · reply_markup для sendMessage
{
  "inline_keyboard": [
    [{"text": "Открыть канал", "url": "https://t.me/example_channel"}],
    [{"text": "Проверить", "callback_data": "check_subscription"}]
  ]
}

Обработчик ниже рассчитан на такую кнопку в личном чате с ботом. Он принимает проверенное входящее update и callable $call, возвращающий result метода Bot API или выбрасывающий исключение. Это граница с вашим HTTP-клиентом; готовое подключение BotGate показано дальше.

PHP · check-subscription.php
<?php
declare(strict_types=1);
require_once __DIR__ . '/membership.php';

function checkSubscription(array $update, int|string $channelId, callable $call): ?array
{
    $q = $update['callback_query'] ?? null;
    if (!is_array($q) || ($q['data'] ?? null) !== 'check_subscription'
        || !is_string($q['id'] ?? null)
        || !is_int($q['from']['id'] ?? null)
        || ($q['from']['is_bot'] ?? false)
        || ($q['message']['chat']['type'] ?? null) !== 'private'
        || ($q['message']['chat']['id'] ?? null) !== $q['from']['id']) {
        return null;
    }
    $userId = $q['from']['id'];
    // Сначала закрываем индикатор на кнопке. Ошибка старого callback
    // не должна превращаться в решение о подписке.
    try {
        $call('answerCallbackQuery', [
            'callback_query_id' => $q['id'], 'text' => 'Проверяем подписку…',
        ]);
    } catch (Throwable) {
        // Здесь можно увеличить отдельный технический счётчик.
    }
    try {
        $member = $call('getChatMember', ['chat_id' => $channelId, 'user_id' => $userId]);
        $status = is_array($member) ? membershipStatus($member, $userId) : 'unknown';
    } catch (Throwable) {
        $status = 'unknown';
    }
    return ['user_id' => $userId, 'chat_id' => $userId, 'status' => $status];
}

user_id берётся из callback_query.from.id. Не используйте message.from.id: там обычно находится сам бот, отправивший клавиатуру. ID канала не принимается из callback_data. Значение check_subscription — только выбранное действие, а не доказательство права на материал.

После возврата yes сохраните выдачу материала с уникальным ключом (bot_id, user_id, material_id). В одной транзакции создайте запись выдачи и задание на отправку, чтобы повторное нажатие не создавало новые выдачи. Сам sendMessage тоже требует контроля неизвестного результата. Механика кнопок подробнее разобрана в статье про inline-кнопки.

Что делать при ошибках и частых нажатиях

  • Не хватает прав или неверный chat_id: проверьте настройки канала; пользователю покажите временную невозможность проверки.

  • Telegram вернул 429: используйте retry_after и отложите проверку. Не делайте цикл запросов внутри webhook.

  • Таймаут или 5xx: оставьте unknown. Повтор чтения getChatMember не выдаёт материал сам по себе; выдачу всё равно защищает отдельный уникальный ключ.

  • Пользователь много раз нажал кнопку: ограничьте частоту по боту и пользователю. Коротко переиспользуйте свежий результат или сообщите, что проверка уже идёт.

  • Заявка на вступление ещё не одобрена: не считайте её участием. Предложите повторить после принятия.

Обработчик выше не включает кэш, выдачу файла и ограничитель частоты: это точки подключения к хранилищу вашего приложения. Не оставляйте общедоступный endpoint, принимающий произвольные user_id, вместо проверки подлинного webhook.

Подключаем BotGate SDK

Установите composer require botgate/sdk. API-ключ и публичный ID бота передайте через окружение процесса; обычный PHP сам не читает .env. Следующий адаптер передаёт result в checkSubscription. $update должен уже пройти проверку подписи BotGate по исходному телу запроса.

PHP · подключение к обработчику
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/check-subscription.php';

use BotGate\Client;
use BotGate\Config;

$apiKey = getenv('BOTGATE_API_KEY');
$botId = getenv('BOTGATE_BOT_ID');
$channelId = getenv('TELEGRAM_CHANNEL_ID');
if (!$apiKey || !$botId || !$channelId) {
    throw new RuntimeException('Задайте ключ, публичный ID бота и ID канала.');
}
$bot = Client::fromConfig(new Config(
    apiKey: $apiKey, timeout: 10.0, maxRetries: 0,
))->bot($botId);

// $update — декодированное и проверенное входящее событие.
$decision = checkSubscription($update, $channelId,
    static fn(string $method, array $params): mixed => $bot->call($method, $params)->result
);
// $decision === null: событие не относится к этой кнопке.
// status === 'yes': передайте решение в атомарную выдачу материала.
// status === 'no' / 'unknown': подготовьте соответствующий ответ.

Если добавляете планирование повторов, различайте RateLimitException для лимита BotGate и TelegramException с telegramErrorCode() === 429 для лимита Telegram. Оба дают retryAfter(), но причины ограничений различны. Само подключение через шлюз не добавляет боту прав в канале. См. ошибку 429 и повторы и проверку webhook.

Проверяем решение, а не только HTTP-ответ

  • Проверьте member, administrator и creator: каждый должен давать yes.

  • Проверьте left и kicked: оба должны давать no.

  • Для restricted проверьте true, false и отсутствующий is_member.

  • Подставьте ответ с чужим user.id, неизвестным status, ошибку транспорта и 429: результат должен быть unknown.

  • Нажмите кнопку другим пользователем: запрос должен проверять нового отправителя, а не автора первоначального теста.

  • Уберите права администратора у тестового бота: ошибка проверки не должна сообщать подписчику, что он вышел из канала.

  • Повторите успешный callback: право выдаётся один раз, повторная обработка не создаёт второй бизнес-операции.

Документация