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