Практика лимитов Telegram Bot API: обработка 429 Retry-After, очереди и батчинг на PHP

При масштабировании Telegram-бота или запуске массовых уведомлений разработчики неизбежно сталкиваются с ответом HTTP 429 Too Many Requests. Игнорирование лимитов Telegram Bot API приводит к потере сообщений, зависанию вебхуков и даже к временной или вечной блокировке бота со стороны платформы. В этой статье мы подробно разберем официальные и практические ограничения Bot API, реализуем корректную обработку ретраев на PHP и спроектируем архитектуру очереди исходящих сообщений.

Официальные и фактические лимиты Telegram Bot API

Telegram накладывает жесткие рамки на количество отправляемых запросов. Эти ограничения распределены по нескольким уровням:

  • Глобальный лимит бота: не более 30 сообщений в секунду суммарно по всем чатам.
  • Лимит на конкретный приватный чат: не более 1 сообщения в секунду. Отправка 2–3 сообщений подряд одному пользователю за секунду неизбежно вызовет ошибку 429.
  • Лимит на группы и каналы: не более 20 сообщений в минуту в одну группу или канал.
  • Лимит на редактирование/удаление: частые вызовы editMessageText или deleteMessage подпадают под те же ограничения в 1 запрос в секунду на чат.

При превышении любого из этих порогов сервер Telegram возвращает HTTP-статус 429 и JSON-ответ содержащий поле parameters.retry_after, где указано число секунд, которое необходимо выждать перед повторным запросом.

Реализация cURL-клиента с авто-повтором при 429

Для надежного взаимодействия с API нельзя использовать банальный file_get_contents. Обязательно требуется cURL с явной проверкой заголовков, парсингом JSON-ошибок и учетом retry_after.

Ниже представлен рабочий пример функции отправки запросов к Bot API с поддержкой повторных попыток:

function sendTelegramApiRequest(string $method, array $payload, int $maxRetries = 3): array
{
$botToken = getenv('TELEGRAM_BOT_TOKEN');
if (!$botToken) {
throw new RuntimeException('TELEGRAM_BOT_TOKEN environment variable is missing.');
}

$url = "https://api.telegram.org/bot{$botToken}/{$method}";
$attempt = 0;

while ($attempt < $maxRetries) {
$attempt++;
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_CONNECTTIMEOUT => 5,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);

if ($response === false) {
throw new RuntimeException("cURL error during request to {$method}: {$error}");
}

$decoded = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
throw new RuntimeException("Invalid JSON response from Telegram API: " . json_last_error_msg());
}

if ($httpCode === 429) {
$retryAfter = $decoded['parameters']['retry_after'] ?? 1;
sleep((int)$retryAfter + 1);
continue;
}

if (isset($decoded['ok']) && $decoded['ok'] === true) {
return $decoded;
}

$errorCode = $decoded['error_code'] ?? $httpCode;
$description = $decoded['description'] ?? 'Unknown API error';

return [
'ok' => false,
'error_code' => $errorCode,
'description' => $description,
];
}

return ['ok' => false, 'description' => 'Max retries exceeded due to rate limits'];
}

Архитектура очереди исходящих сообщений и задержки (Throttling)

Отправлять рассылку синхронно прямо в HTTP-запросе вебхука или контроллера сайта — главная ошибка новичков. Вебхук Telegram ожидает ответ 200 OK в течение нескольких секунд. Если задерживать ответ из-за массовой отправки, Telegram начнет повторно присылать те же update_id, что вызовет лавинообразный шторм запросов.

Правильный подход: складывать задачи на отправку в таблицу БД или Redis, а фоновый демон (Worker) отправляет их с соблюдением лимитов.

function processOutboundQueue(PDO $pdo): void
{
$stmt = $pdo->prepare("SELECT id, chat_id, payload_json FROM telegram_queue WHERE status = 'pending' ORDER BY id ASC LIMIT 30");
$stmt->execute();
$messages = $stmt->fetchAll(PDO::FETCH_ASSOC);

if (empty($messages)) {
return;
}

$updateStatusStmt = $pdo->prepare("UPDATE telegram_queue SET status = :status, error_message = :err, updated_at = NOW() WHERE id = :id");

foreach ($messages as $msg) {
$payload = json_decode($msg['payload_json'], true);
if (!$payload) {
$updateStatusStmt->execute([':status' => 'failed', ':err' => 'Invalid JSON payload', ':id' => $msg['id']]);
continue;
}

$result = sendTelegramApiRequest('sendMessage', $payload);

if ($result['ok']) {
$updateStatusStmt->execute([':status' => 'sent', ':err' => null, ':id' => $msg['id']]);
} else {
$errorCode = $result['error_code'] ?? 0;
$desc = $result['description'] ?? 'Unknown error';

if ($errorCode === 403) {
// Пользователь заблокировал бота — помечаем статус и отключаем активный флаг у профиля
$updateStatusStmt->execute([':status' => 'blocked', ':err' => $desc, ':id' => $msg['id']]);
$deactivateStmt = $pdo->prepare("UPDATE users SET is_active = 0 WHERE telegram_chat_id = :chat_id");
$deactivateStmt->execute([':chat_id' => $msg['chat_id']]);
} else {
$updateStatusStmt->execute([':status' => 'failed', ':err' => $desc, ':id' => $msg['id']]);
}
}

// Задержка ~35 миллисекунд гарантирует соблюдение глобального лимита в 30 собщ/сек
usleep(35000);
}
}

Валидация Webhook и дедупликация incoming updates

При обработке входящих вебхуков важную роль играют безопасность и защита от повторной обработки (идемпотентность). Если обработка входящего события падает с ошибкой, Telegram повторит запрос. Поэтому необходимо сохранять update_id и валидировать заголовок X-Telegram-Bot-Api-Secret-Token.

function handleTelegramWebhook(PDO $pdo): void
{
$secretHeader = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
$expectedSecret = getenv('TELEGRAM_WEBHOOK_SECRET');

if ($secretHeader !== $expectedSecret) {
http_response_code(403);
echo json_encode(['error' => 'Invalid secret token']);
exit;
}

$input = file_get_contents('php://input');
$update = json_decode($input, true);

if (json_last_error() !== JSON_ERROR_NONE || !isset($update['update_id'])) {
http_response_code(400);
echo json_encode(['error' => 'Invalid update payload']);
exit;
}

$updateId = (int)$update['update_id'];

// Проверка идемпотентности по сохраненным update_id
$checkStmt = $pdo->prepare("SELECT id FROM telegram_processed_updates WHERE update_id = :update_id");
$checkStmt->execute([':update_id' => $updateId]);
if ($checkStmt->fetch()) {
http_response_code(200);
echo json_encode(['ok' => true, 'status' => 'duplicate_ignored']);
exit;
}

// Фиксация входящего update_id
$insertStmt = $pdo->prepare("INSERT INTO telegram_processed_updates (update_id, created_at) VALUES (:update_id, NOW())");
$insertStmt->execute([':update_id' => $updateId]);

// Дальнейшая передача в обработчик бизнес-логики...
http_response_code(200);
echo json_encode(['ok' => true]);
}

Что ломается при рассылках и как с этим жить

Во время масштабных рассылок проявляется ряд нюансов, не заметных при тестировании на одиночных чатах:

  1. Рост ошибок 403 Forbidden: От 5% до 20% аудитории при рассылке могут оказаться заблокировавшими бота. Если продолжать отправку по таким пользователям, Telegram расценивает это как спам. Нужно немедленно исключать их из списков рассылки в БД.
  2. Склеивание и батчинг сообщений: Вместо 5 отдельных коротких уведомлений (например, о статусе заказа) объединяйте их в один HTML-блок с помощью форматирования. Это бережет лимит 1 собщ/сек на пользователя.
  3. Неверная длина callback_data: Напоминаем, что параметр callback_data в InlineKeyboardButton ограничен строго 64 байтами. Использование идентификаторов вроде lead_id = bin2hex(random_bytes(7)) позволяет экономить место и связывать клики с записями в БД.
Соблюдение лимитов Telegram Bot API — ключ к стабильной работе ваших сервисов без потерь уведомлений и санкций со стороны мессенджера.

Если вам нужна профессиональная разработка масштабируемых ботов и Mini Apps без риска блокировок API, команда BotCreator поможет реализовать проект любой сложности.

Новые статьи — в Telegram

Разбираем, что автоматизировать в бизнесе и как это работает на практике. Без спама.