Ліміти Telegram Bot API: повідомлення на секунду, помилка 429 і розміри файлів
Головні ліміти Telegram Bot API такі: не більше одного повідомлення на секунду в один чат, до 20 повідомлень на хвилину в групу і близько 30 повідомлень на секунду під час масової розсилки. За перевищення бот отримує помилку 429 Too Many Requests з полем retry_after. Для файлів діють свої межі: вивантаження до 50 МБ, завантаження через getFile — до 20 МБ. Нижче зібрано всі обмеження з цифрами та код, який коректно переживає rate limit.
Ліміт повідомлень: скільки може надіслати бот
Точного алгоритму flood control Telegram не публікує, але в офіційному Bots FAQ є орієнтири:
| Сценарій | Ліміт | Коментар |
|---|---|---|
| Один чат | ≈ 1 повідомлення на секунду | Короткі сплески допустимі, але потім почнуться помилки 429 |
| Група | 20 повідомлень на хвилину | У середньому одне повідомлення на 3 секунди |
| Масова розсилка | ≈ 30 повідомлень на секунду | Сумарно для всіх чатів бота |
| Платна розсилка | до 1000 повідомлень на секунду | 0,1 Telegram Stars за кожне повідомлення понад безплатні 30 на секунду |
Ліміти стосуються повідомлень будь-якого типу: фото, документ чи опитування — теж повідомлення. У тестовому середовищі Telegram ліміти не підвищені, а часом навіть суворіші, тож не зашивайте цифри в код намертво — надійніше обробляти 429 і повторювати запит.
Помилка 429 Too Many Requests і retry_after
Коли бот перевищує ліміт, Telegram відповідає так:
{
"ok": false,
"error_code": 429,
"description": "Too Many Requests: retry after 14",
"parameters": {"retry_after": 14}
}
Поле parameters.retry_after — кількість секунд, після яких запит можна повторити. Правильна реакція — витримати паузу й надіслати той самий запит ще раз, а не повторювати його одразу в циклі. Обгортка на Python або JavaScript (Node.js 18+):
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API_URL = f"https://api.telegram.org/bot{TOKEN}"
def call(method, max_retries=5, **params):
"""Викликає метод Bot API і сам чекає у разі помилки 429."""
for _ in range(max_retries):
data = requests.post(f"{API_URL}/{method}", json=params, timeout=30).json()
if data["ok"]:
return data["result"]
if data["error_code"] == 429:
time.sleep(data.get("parameters", {}).get("retry_after", 1) + 1)
continue
raise RuntimeError(f"{data['error_code']}: {data['description']}")
raise RuntimeError(f"{method}: перевищено кількість повторів")const API_URL = `https://api.telegram.org/bot${process.env.BOT_TOKEN}`;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(method, params = {}, maxRetries = 5) {
for (let i = 0; i < maxRetries; i++) {
const res = await fetch(`${API_URL}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(params),
});
const data = await res.json();
if (data.ok) return data.result;
if (data.error_code !== 429) throw new Error(`${data.error_code}: ${data.description}`);
await sleep(((data.parameters?.retry_after ?? 1) + 1) * 1000);
}
throw new Error(`${method}: перевищено кількість повторів`);
}У багатьох бібліотеках це вже розв'язано: у python-telegram-bot є AIORateLimiter, у grammY — плагін auto-retry. Перегляньте документацію своєї бібліотеки, перш ніж писати власний механізм.
Як зробити розсилку й не впертися в rate limit
- Ставте повідомлення в чергу, а не надсилайте все разом із паралельних задач.
- Тримайте загальний темп із запасом — 20–25 повідомлень на секунду замість граничних 30.
- В один чат пишіть не частіше ніж раз на секунду, у групу — не частіше ніж раз на 3 секунди.
- Отримавши 429, призупиніть усю чергу на
retry_afterсекунд, а не лише поточний чат. - На
403 Forbidden: bot was blocked by the userвидаляйте користувача з бази розсилки — повторювати безглуздо. - Великі розсилки розтягуйте в часі: Bots FAQ радить розподіляти їх на 8–12 годин.
def broadcast(chat_ids, text, per_second=25):
blocked = []
for chat_id in chat_ids:
try:
call("sendMessage", chat_id=chat_id, text=text)
except RuntimeError as err:
if str(err).startswith("403"):
blocked.append(chat_id) # бота заблоковано — вилучити з бази
time.sleep(1 / per_second)
return blockedasync function broadcast(chatIds, text, perSecond = 25) {
const blocked = [];
for (const chatId of chatIds) {
try {
await call('sendMessage', { chat_id: chatId, text });
} catch (err) {
if (err.message.startsWith('403')) {
blocked.push(chatId); // бота заблоковано — вилучити з бази
}
}
await sleep(1000 / perSecond);
}
return blocked;
}Функція call з прикладу вище сама перечекає 429 (і разом із нею зупиниться весь цикл), а пауза після кожного повідомлення тримає темп.
Платні розсилки: allow_paid_broadcast
Якщо 30 повідомлень на секунду замало, увімкніть Paid Broadcasts у @BotFather і передавайте в методах надсилання параметр allow_paid_broadcast. Ліміт зросте до 1000 повідомлень на секунду, а кожне повідомлення понад безплатні 30 на секунду коштуватиме 0,1 Telegram Stars з балансу бота. Stars списуються лише за успішно розіслані повідомлення.
{"chat_id": 123456789, "text": "Розпродаж почався!", "allow_paid_broadcast": true}
Поріг входу високий: для ввімкнення функції потрібні мінімальний баланс Stars і достатня активна аудиторія бота. Актуальні цифри перевірте в Bots FAQ, а невеликим ботам простіше розтягнути розсилку в часі.
Ліміти Telegram Bot API на розмір файлів
| Операція | Ліміт |
|---|---|
Вивантаження через multipart/form-data | фото — до 10 МБ, інші файли — до 50 МБ |
| Надсилання за HTTP-посиланням (Telegram завантажить файл сам) | фото — до 5 МБ, решта — до 20 МБ |
Повторне надсилання за file_id | без обмежень за розміром |
Завантаження через getFile | до 20 МБ |
| Локальний Bot API сервер | вивантаження до 2000 МБ, завантаження без обмежень |
Ще кілька нюансів із документації. У фото сума ширини й висоти не повинна перевищувати 10 000, а співвідношення сторін — 20. sendDocument за URL зараз працює лише для файлів .PDF і .ZIP. Посилання на завантаження вигляду https://api.telegram.org/file/bot<token>/<file_path> з відповіді getFile діє щонайменше годину, потім запросіть нове. Перевірити розмір файлу перед завантаженням можна в getFile у Bot API Tester — дивіться поля file_size і file_path. Якщо бот має приймати від користувачів файли, більші за 20 МБ, знадобиться локальний Bot API сервер.
Ліміти на текст, кнопки й альбоми
| Що | Ліміт |
|---|---|
text у sendMessage | 1–4096 символів після розбору розмітки |
caption у фото, відео й документів | 0–1024 символи |
callback_data inline-кнопки | 1–64 байти |
Текст сповіщення в answerCallbackQuery | 0–200 символів |
Альбом (sendMediaGroup) | 2–10 елементів |
| Результати inline-запиту | не більше 50 за одну відповідь |
Команди бота (setMyCommands) | до 100 команд |
Rich-повідомлення (sendRichMessage) | до 32 768 символів, 500 блоків, 50 медіа, 20 стовпців у таблиці |
Не плутайте символи й байти: callback_data рахується в байтах UTF-8, тому кирилиці туди вміститься вдвічі менше, ніж латиниці. Довгий текст ріжте на частини по межах абзаців — так не розірвуться HTML-теги й сутності MarkdownV2.
Ліміти на отримання оновлень
- Вхідні апдейти зберігаються на серверах Telegram не довше 24 годин.
getUpdatesвіддає за раз від 1 до 100 апдейтів (параметрlimit, за замовчуванням 100). Підтверджуйте отримані, передаючиoffset= останнійupdate_id+ 1.- Вебхук:
max_connections— від 1 до 100 одночасних з'єднань (за замовчуванням 40), на локальному сервері — до 100 000. getUpdatesі вебхук взаємовиключні: поки вебхук встановлено, long polling не працює (409 Conflict).
Як налаштувати вебхук і не втратити апдейти, розповідає гайд вебхук для телеграм-бота.
Чому бот отримує 429, хоча надсилає небагато
- Усе йде в один чат. Для окремого чату й групи ліміти жорсткіші за загальні: якщо надсилати 3–4 повідомлення на секунду в один чат, 429 рано чи пізно прийде, хоча до 30 на секунду далеко.
- Токен ділять кілька процесів. Воркери, cron-задачі, другий екземпляр бота на сусідньому сервері — ліміт рахується для бота загалом, а не для кожного процесу.
- Повтори без паузи. Код ловить помилку й одразу надсилає запит знову, не чекаючи
retry_after. Використовуйте обгортку на кшталтcallвище. - Тести в тестовому середовищі. Там ліміти не вищі за бойові й іноді суворіші, тож «у проді все було нормально» нічого не гарантує.
- Сплеск після перезапуску. Бот разом відповідає на накопичені апдейти. Обробляйте їх із тим самим обмеженням темпу, що й розсилку, або скиньте старі апдейти параметром
drop_pending_updatesуsetWebhookчиdeleteWebhook.
Перевірте на практиці
Відкрийте getUpdates у Bot API Tester, щоб побачити, скільки апдейтів чекає на бота, або надішліть пробне повідомлення через sendMessage — у відповіді видно поле ok, а в разі помилки й retry_after. Форматування й кнопки розібрано в гайді як надіслати повідомлення через бота, а нові rich-повідомлення та їхні обмеження — в огляді що нового в Telegram Bot API 10.5.
Поширені запитання
Скільки повідомлень на секунду може надсилати телеграм-бот?
Орієнтири з Bots FAQ: близько 30 повідомлень на секунду під час масової розсилки, не більше 1 повідомлення на секунду в один чат і до 20 повідомлень на хвилину в групу. З allow_paid_broadcast — до 1000 повідомлень на секунду за Telegram Stars.
Що означає помилка 429 Too Many Requests у Telegram?
Бот перевищив ліміт частоти запитів. У відповіді є parameters.retry_after — стільки секунд треба зачекати, перш ніж повторити запит.
Який максимальний розмір файлу для телеграм-бота?
Під час завантаження через multipart/form-data — 50 МБ (фото — 10 МБ), під час надсилання за URL — 5 МБ для фото і 20 МБ для інших файлів. Повторне надсилання за file_id не обмежене, а локальний Bot API сервер приймає файли до 2000 МБ.
Чому бот не може завантажити файл, більший за 20 МБ?
Метод getFile хмарного Bot API працює лише з файлами до 20 МБ. Для більших файлів потрібен локальний Bot API сервер — на ньому обмеження на завантаження немає.
Яка максимальна довжина повідомлення бота?
4096 символів для text і 1024 символи для підпису до медіа, рахуючи після розбору розмітки. Довший текст доведеться розбити на кілька повідомлень.
Скільки Telegram зберігає апдейти для бота?
Не довше 24 годин. Якщо бот не забрав їх через getUpdates або вебхук, вони видаляються.
Читайте також
Як створити бота в Телеграм: від @BotFather до першого повідомлення
Як створити бота в Телеграм: реєстрація в @BotFather, токен, перевірка через getMe, перше повідомлення на curl і Python, команди та опис бота.
Що нового в Telegram Bot API 10.0–10.5: налаштування бота, віджети, rich-повідомлення, ефемерні повідомлення й гостьовий режим
Що нового в Telegram Bot API 10.0–10.5: setMySettings і BotFullInfo, HTML-віджети, rich- та ефемерні повідомлення, гостьовий режим — з прикладами.
Як надіслати повідомлення через бота Telegram: sendMessage, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через getUpdates: особистий чат, група, супергрупа, канал і тема форуму. Формати id з -100 і що робити з порожнім result.
Тестовий сервер Telegram: як тестувати бота в тестовому середовищі
Тестовий сервер Telegram для ботів: вхід у тестове середовище, створення тестового бота, запити до Bot API через /test/ і перемикач TEST у тестері.
Віджети Telegram для сайту: вхід через Telegram, вбудовування постів, коментарі й кнопка «Поділитися»
Вхід через Telegram на сайті: новий Telegram Login (OIDC), старий Login Widget із перевіркою hash, вбудовування постів, коментарі та кнопка «Поділитися».
TelegramWidget JavaScript API: властивості, події, коди помилок і ліміти
Довідник TelegramWidget API: властивості, request(), події, коди помилок, CSS-змінні, widget_query та answerWidgetQuery, а також усі ліміти віджетів.
Приклади віджетів Telegram: готовий HTML і код бота на Python
Робочі приклади віджетів Telegram із повним кодом: картка замовлення, лічильник із запитами widget_query, спільне живе опитування та прев'ю в браузері.
Віджети Telegram: інтерактивний HTML просто в повідомленнях бота
Віджети Telegram у Bot API 10.4: що це, як працюють sendWidget, chat_data і public_data, де віджети доступні зараз і чим вони відрізняються від Mini Apps.
Тестування Telegram Mini App: від браузера до налагодження на телефоні
Тестування Telegram Mini App крок за кроком: mock-режим у браузері, HTTPS-тунель для localhost, тестове середовище, DevTools на телефоні та initData.