Ліміти Telegram Bot API на масштабі: де ламається і як не вийти за межі

Ліміти Telegram Bot API на масштабі: де ламається і як не вийти за межі

Коротко. Bot API дозволяє приблизно 1 повідомлення на секунду в один і той самий чат, 30 повідомлень на секунду на розсилку до різних чатів і близько 20 повідомлень на хвилину в один канал чи групу. Перетин будь-якого ліміту — це HTTP 429 із parameters.retry_after у секундах. Завдання вашого коду — поважати цю паузу, ставити решту в чергу і не вибухати пачкою. Ліміт на завантаження фото — 10 МБ для multipart-аплоаду (5 МБ, якщо Telegram тягне фото за URL), на інші файли через публічний Bot API — 50 МБ.

Тримаєте кілька каналів і не хочете писати чергу самотужки? Подивіться, як Autogram батчить пости під ліміти.

Що саме обмежує Bot API

Photo by Brett Sayles on Pexels

Ключові цифри Telegram задокументовані у Bot API FAQ про розсилку — їх легко запам'ятати, але важко витримати на масштабі:

Два ліміти, які варто витатуювати на руці: 20 повідомлень за хвилину в один канал (стеля редакційного потоку) і 30 повідомлень на секунду до різних чатів (стеля broadcast). Тривало працюючі деплойменти першими впираються у канальний ліміт, бо саме там накопичується редакційний обсяг; broadcast-боти першими б'ються об ліміт між чатами, бо ріст аудиторії непомітно проштовхує їх за межу.

Це не всі обмеження. Будь-яка модифікація стану повідомлення — editMessageText, deleteMessage, forwardMessage, copyMessage, setMessageReaction — теж рахується у вашому бюджеті відправок. У ботів inline-режиму є окремий набір обмежень за латентністю в answerInlineQuery, і вони форсуються таймаутами для користувача, а не 429 у відповіді.

Як throttling працює на практиці

Photo by RDNE Stock project on Pexels

Коли ви перетинаєте ліміт, Telegram повертає HTTP 429 Too Many Requests із JSON-тілом, у якому за референсом making-requests присутнє parameters.retry_after — ціле значення в секундах. Реальна відповідь виглядає так:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 17",
  "parameters": { "retry_after": 17 }
}

Правильна послідовність дій — три кроки:

1. Зупиніть відправки тільки в межах заблокованої області. Якщо 429 прилетіло на конкретний канал — заморозьте записи в цей канал, а не весь worker pool.
2. Поспіть retry_after секунд плюс невеликий jitter (200–500 мс). Без jitter усі воркери повернуться на однаковому такті і знов виб'ють ліміт.
3. Повторіть той самий запит. Модель ідемпотентності Telegram припускає, що падаючий виклик не створив повідомлення; успішна повторна спроба не задублює.

Більшість продакшен-бібліотек це вже роблять. aiogram і python-telegram-bot дають готові обробники RetryAfter; черга pyrogram робить те саме неявно. Чого вони не роблять — це передбачення ліміту: вони реагують на 429 постфактум. На масштабі це коштує невеликої хвилі невдалих запитів на кожен сплеск, тож наступний розділ важливий.

Стратегії батчингу, які тримають вас під капом

Три патерни покривають близько 95% високонавантажених Telegram-автоматизацій:

1. Token-bucket на кожен скоуп. Тримайте in-memory bucket на кожен chat ID і глобальний bucket із 30 токенами та поповненням раз на секунду. Не відправляйте, поки немає токена. Це повністю прибирає 429-сплески. Bucket на Redis працює крізь worker pool; одно-процесний бот може використати asyncio-throttle або еквівалент.

2. Media groups замість циклів. Виклик sendMediaGroup публікує до 10 фото або відео як єдиний альбом і рахується як один запит у канальному капі. Розкатка з 50 зображень падає з 50 повідомлень (фактично неможливих — це 2,5 хвилини обережного pacing) до 5 альбомів — спокійно під капом за хвилину. Та ж логіка працює усюди, де API дозволяє згорнути N викликів в один конверт.

3. Редакційне згладжування. Якщо планувальник намагається відправити 100 канальних постів рівно о 09:00, жодна клієнтська математика лімітів вас не врятує — ви розіб'єтесь об edge Telegram ще до того, як bucket встигне вирішити. Розподіляйте чергу по годині на ходу або заздалегідь розставляйте слоти. Двохвилинний крок між записами в один канал — безпечний дефолт; одна хвилина — підлога, нижче якої починається з'їдання канального ліміту.

Архітектурні патерни для масштабу

Photo by Keysi Estrada on Pexels

Як тільки один бот починає відправляти більш ніж ~100 тис. повідомлень на день, чотири архітектурні рішення перестають бути опційними:

• Один токен — одна вихідна черга. Всі відправки йдуть через єдину FIFO-чергу на токен. Воркерів може бути багато, але рішення про throttle мусить бути централізованим — розподілений token-bucket б'є per-worker евристики щоразу.
• Self-hosted Bot API server для високотрафікових акаунтів. Telegram відкрив TDLib-based local Bot API server. Він знімає ліміт на завантаження файлу до 2 ГБ, зменшує медіану latency і дає повний контроль над connection pool і routingом вебхуків.
• Розділяйте broadcast-ботів і інтерактивних. Розсилки, які вибухають об 30/сек, не повинні ділити токен з ботом, який відповідає на /start чи обробляє inline-запити. Заблокований токен — це заблокований токен — розділіть і тримайте broadcast-токен як write-only worker.
• Спостережуваність по retry_after. Лічіть кількість 429 за хвилину і ковзне середнє retry_after. Здоровий парк показує плоску лінію біля нуля; зростаюче середнє означає, що розмір вашого token-bucket розходиться з реальною ємністю Telegram, і платформа робить ту back-pressure, що мала б бути у вашому планувальнику.

Якщо ви на керованому планувальнику — Autogram, наприклад — більшість цього живе за API і ви нічого не пишете. Прочитати розділ варто хоча б для того, щоб коли клієнт запитає «чому хвиля о 09:00 приземлилася о 09:04», у вас була правильна відповідь, а не знизання плечима.

Дотичне читання

• Масова розсилка в Telegram: посібник для агенцій — як планувати високообсягові розкатки, не вибиваючи flood control.
• Автопостинг у Telegram без позначки «Переслано» — маршрут через copyMessage, який рахується у бюджеті так само, як sendMessage.
• No-code автоматизація Telegram: Zapier vs Make vs ManyBot vs Autogram — як Zapier, Make і ManyBot обходять (або тихо приховують) стелю по лімітах.

FAQ

Що насправді означає «помилка Telegram bot 429»?

Це означає, що ваш запит перетнув один з лімітів Telegram у конкретному скоупі. У відповіді є parameters.retry_after у секундах — поспіть стільки і повторіть той самий запит. 429 — це load-shedding, а не остаточна помилка.

Telegram flood control — це те саме, що ліміти Bot API?

Ні. «Flood control» у клієнті чи userbot-світі — це обмеження MTProto, що ескалюють до тимчасових банів акаунту. Ліміти Bot API м'якіші, скоупо-специфічні і скидаються за секунди. Конверт 429 з retry_after — це особливість саме Bot API.

Скільки повідомлень за секунду може відправити Telegram-бот?

До 30 між різними чатами (broadcast-скоуп) і приблизно 1 у один чат. Запис в один канал — близько 20 за хвилину, тобто одне на 3 секунди в стійкому графіку.

Чи можна підняти ліміт Telegram-бота?

Так, для розсилок. Функція Paid Broadcasts (вмикається через @BotFather) піднімає broadcast-ліміт із 30 повідомлень на секунду до 1 000 повідомлень на секунду; кожне повідомлення понад безкоштовні 30/сек коштує 0,1 Telegram Stars, а баланс бота має бути не меншим за 10 000 Stars. Не-broadcast ліміти (1/сек на чат, 20/хв на канал) лишаються фіксованими. Self-hosted Bot API server піднімає ліміт на завантаження файлу до 2 ГБ, але не піднімає лімітів на відправлення повідомлень.

Як уникнути потрапляння в ліміт Bot API?

Запустіть token-bucket на кожен скоуп (чат, канал, глобальний), батчте через sendMediaGroup де можна, згладжуйте редакційні черги по годині й інструментуйте 429, щоб бачити дрейф раніше за користувачів.

Що буде, якщо ігнорувати 429 retry_after?

Telegram збільшить back-off і може тимчасово вимкнути токен. Якщо ігнорувати довго — потрапите в поле зору команди платформи, а це гірша проблема, ніж початкова про пропускну здатність.

sendMediaGroup рахується як одне повідомлення чи кілька?

Як одне. Media group — один виклик Bot API незалежно від того, чи вкладено 2 чи 10 файлів. Саме тому це найнадійніший важіль, щоб триматися під канальним лімітом за хвилину.

Підсумок

Ліміти Telegram Bot API м'які, добре задокументовані й скидаються за секунди — але кожний продакшен-бот рано чи пізно в них впирається, зазвичай о 09:00 у день запуску. Зробіть token-bucket, поважайте retry_after, батчте через media groups і виносьте broadcast на окремий токен. Autogram робить це за вас, тож єдина цифра, про яку доведеться думати, — «скільки каналів».

Image credits

• Hero: Photo by Brett Sayles on Pexels.
• Inline #1: Photo by RDNE Stock project on Pexels.
• Inline #2: Photo by Keysi Estrada on Pexels.