Під час масштабування 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 допоможе реалізувати проєкт будь-якої складності.