Готовим канал и права бота
Метод 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 в журналах.
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
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 и явный срок жизни. Не превращайте единственный успешный ответ в бессрочное право.
Что делать при ошибках и частых нажатиях
Не хватает прав или неверный 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
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: право выдаётся один раз, повторная обработка не создаёт второй бизнес-операции.