Telegram Bot API

Ліміти Telegram Bot API: повідомлення на секунду, помилка 429 і розміри файлів

· 8 хв читання

Головні ліміти 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

  1. Ставте повідомлення в чергу, а не надсилайте все разом із паралельних задач.
  2. Тримайте загальний темп із запасом — 20–25 повідомлень на секунду замість граничних 30.
  3. В один чат пишіть не частіше ніж раз на секунду, у групу — не частіше ніж раз на 3 секунди.
  4. Отримавши 429, призупиніть усю чергу на retry_after секунд, а не лише поточний чат.
  5. На 403 Forbidden: bot was blocked by the user видаляйте користувача з бази розсилки — повторювати безглуздо.
  6. Великі розсилки розтягуйте в часі: 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 blocked
async 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 (і разом із нею зупиниться весь цикл), а пауза після кожного повідомлення тримає темп.

Якщо 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 у sendMessage1–4096 символів після розбору розмітки
caption у фото, відео й документів0–1024 символи
callback_data inline-кнопки1–64 байти
Текст сповіщення в answerCallbackQuery0–200 символів
Альбом (sendMediaGroup)2–10 елементів
Результати inline-запитуне більше 50 за одну відповідь
Команди бота (setMyCommands)до 100 команд
Rich-повідомлення (sendRichMessage)до 32 768 символів, 500 блоків, 50 медіа, 20 стовпців у таблиці

Не плутайте символи й байти: callback_data рахується в байтах UTF-8, тому кирилиці туди вміститься вдвічі менше, ніж латиниці. Довгий текст ріжте на частини по межах абзаців — так не розірвуться HTML-теги й сутності MarkdownV2.

Ліміти на отримання оновлень

Як налаштувати вебхук і не втратити апдейти, розповідає гайд вебхук для телеграм-бота.

Чому бот отримує 429, хоча надсилає небагато

Перевірте на практиці

Відкрийте 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.