Практика лімітів 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

Розбираємо, що автоматизувати в бізнесі та як це працює на практиці. Без спаму.