Telegram Bot API

Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens

· 6 min de leitura

No papel, o rate limit do Telegram Bot API é simples: cerca de 1 mensagem por segundo no mesmo chat, 20 mensagens por minuto num grupo e mais ou menos 30 mensagens por segundo somando todos os chats. Passou disso, a API responde 429 Too Many Requests com um valor retry_after. Esta página reúne os limites do Telegram Bot API num lugar só (ritmo de envio, paid broadcasts, tamanho de arquivos, tamanho de texto e updates), com código que mantém o seu bot dentro deles.

Rate limit do Telegram Bot API para envio de mensagens

O Bots FAQ oficial lista estes limites para o envio normal, gratuito:

EscopoLimiteObservações
Um chat≈ 1 mensagem por segundoPicos curtos são tolerados; depois começam os erros 429.
Um grupo20 mensagens por minutoContado por grupo.
Envios em massa≈ 30 mensagens por segundoAté 1000 por segundo com paid broadcasts.

Trate esses números como referência, não como contrato. O Telegram avisa que os limites podem mudar, e no ambiente de testes os limites de flood não são maiores (podem até ser mais rígidos). Código que respeita o retry_after sobrevive a mudanças que quebrariam um "30" fixo no código.

429 Too Many Requests e retry_after

Quando você bate num limite de flood, a resposta é assim:

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

retry_after é o número de segundos até a requisição poder ser repetida. Espere pelo menos esse tempo e envie a mesma requisição de novo; tentar imediatamente só prolonga o bloqueio. Uma função auxiliar em Python ou JavaScript:

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"

def call(method, max_attempts=5, **params):
    for _ in range(max_attempts):
        r = requests.post(f"{API}/{method}", json=params, timeout=30).json()
        if r["ok"]:
            return r["result"]
        if r["error_code"] != 429:
            raise RuntimeError(f'{r["error_code"]}: {r["description"]}')
        time.sleep(r.get("parameters", {}).get("retry_after", 1) + 0.5)
    raise RuntimeError("ainda no rate limit, desistindo")

call("sendMessage", chat_id=123456789, text="Olá")
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params, maxAttempts = 5) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${API}/${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.description);
    await sleep(((data.parameters?.retry_after ?? 1) + 0.5) * 1000);
  }
  throw new Error("ainda no rate limit");
}

Controle o ritmo dos disparos com uma fila

Retries resolvem requisições isoladas. Para newsletters e notificações, você precisa controlar o próprio ritmo de envio, por exemplo com uma taxa global um pouco abaixo de 30 mensagens por segundo:

def broadcast(chat_ids, text, per_second=25):
    for chat_id in chat_ids:
        try:
            call("sendMessage", chat_id=chat_id, text=text)
        except RuntimeError as e:
            print(chat_id, e)  # 403: o usuário bloqueou o bot, remova-o da lista
        time.sleep(1 / per_second)
async function broadcast(chatIds, text, perSecond = 25) {
  for (const chatId of chatIds) {
    try {
      await call("sendMessage", { chat_id: chatId, text });
    } catch (e) {
      console.log(chatId, e.message); // 403: o usuário bloqueou o bot, remova-o da lista
    }
    await sleep(1000 / perSecond);
  }
}

Em produção, rode isso num worker em segundo plano, guarde um timestamp por chat para que nenhum chat receba mais de uma mensagem por segundo e remova os chats que devolvem 403 em vez de tentar de novo. Sem paid broadcasts, o Telegram recomenda espalhar disparos grandes por intervalos mais longos, como 8–12 horas.

Se 30 mensagens por segundo não bastam, ative os paid broadcasts no @BotFather e passe "allow_paid_broadcast": true em métodos de envio como sendMessage, sendPhoto ou sendMediaGroup. O bot passa a poder disparar até 1000 mensagens por segundo. Cada mensagem acima das 30 gratuitas por segundo custa 0,1 Telegram Star do saldo do bot, e só as mensagens enviadas com sucesso são cobradas. Para ter acesso é preciso um saldo mínimo de Stars (o Bots FAQ também menciona um mínimo de audiência), então confira os números atuais na documentação oficial antes de planejar em cima disso.

Limites de tamanho de arquivo do bot do Telegram

OperaçãoLimite
Upload de arquivo com multipart/form-data50 MB
Upload de foto10 MB; largura + altura ≤ 10000, proporção ≤ 20
Enviar foto por URL HTTP5 MB
Enviar outros arquivos por URL HTTP20 MB (sendDocument por URL só funciona com .PDF e .ZIP)
Download com getFile20 MB; o link de download vale por pelo menos 1 hora
Reenviar por file_idSem limite de tamanho

Um servidor local do Bot API derruba as duas maiores restrições: uploads de até 2000 MB e downloads sem limite de tamanho, além de webhooks em HTTP puro em qualquer porta. Chame logOut antes de apontar o bot para o seu próprio servidor. Para conferir um arquivo antes de baixar, chame o getFile no Bot API Tester e veja file_size e file_path.

Tamanho de mensagens e outros limites de conteúdo

ItemLimite
Texto da mensagem1–4096 caracteres depois do parse das entidades
Legenda de mídia0–1024 caracteres
Rich message (sendRichMessage)32768 caracteres UTF-8, 500 blocos, 50 mídias, 20 colunas de tabela
callback_data1–64 bytes
Grupo de mídia2–10 itens
Resposta a inline queryAté 50 resultados
Texto do answerCallbackQuery0–200 caracteres
setMyCommands100 comandos; comando com 1–32 caracteres, descrição com 1–256
Parâmetro start de deep linkAté 64 caracteres: A-Z a-z 0-9 _ -
sendData da Mini AppAté 4096 bytes

callback_data é contado em bytes, e caracteres fora do ASCII (como "ç" e "ã") ocupam 2–4 bytes cada em UTF-8; então guarde um id curto no botão e deixe os detalhes no banco de dados. Textos com mais de 4096 caracteres precisam ser divididos, de preferência nas quebras de linha:

def split_text(text, limit=4000):  # um pouco abaixo de 4096 por segurança
    parts, current = [], ""
    for line in text.splitlines(keepends=True):
        if current and len(current) + len(line) > limit:
            parts.append(current)
            current = ""
        while len(line) > limit:
            parts.append(line[:limit])
            line = line[limit:]
        current += line
    if current:
        parts.append(current)
    return parts
function splitText(text, limit = 4000) { // um pouco abaixo de 4096 por segurança
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // divide em linhas, mantendo o "\n"
    if (current && current.length + line.length > limit) {
      parts.push(current);
      current = "";
    }
    while (line.length > limit) {
      parts.push(line.slice(0, limit));
      line = line.slice(limit);
    }
    current += line;
  }
  if (current) parts.push(current);
  return parts;
}

Limites de updates e de webhook

Como ficar dentro dos limites do Telegram Bot API

Guias relacionados: enviar mensagens pela API do Telegram cobre formatação e erros por mensagem, configurar o webhook explica como receber updates em escala e novidades do Bot API 10 apresenta as rich messages e seus limites.

Perguntas frequentes

Qual é o rate limit do Telegram Bot API?

O FAQ de bots do Telegram dá três números: evite mais de 1 mensagem por segundo no mesmo chat, não envie mais de 20 mensagens por minuto num grupo e fique em cerca de 30 mensagens por segundo em envios em massa. Passou disso, a API responde 429 Too Many Requests.

Como resolver o 429 Too Many Requests no Telegram?

Leia parameters.retry_after no erro, espere esse número de segundos e repita a mesma requisição. Para parar de bater no limite, envie tudo por uma fila que controla o ritmo por chat e no total.

Qual o limite de tamanho de arquivo de um bot do Telegram?

Bots podem enviar arquivos de até 50 MB (fotos até 10 MB) e baixar arquivos de até 20 MB com getFile. Por URL, o limite é 5 MB para fotos e 20 MB para os demais arquivos. Um servidor local do Bot API permite uploads de até 2000 MB e downloads sem limite de tamanho.

Qual o tamanho máximo de uma mensagem de bot no Telegram?

Uma mensagem de texto pode ter 1–4096 caracteres depois do parse das entidades e uma legenda de mídia 0–1024 caracteres, então textos maiores precisam ser divididos. Rich messages (Bot API 10.1+) aceitam até 32768 caracteres UTF-8.

Como um bot do Telegram envia mais de 30 mensagens por segundo?

Ative os paid broadcasts no @BotFather e passe allow_paid_broadcast: true. O bot passa a poder enviar até 1000 mensagens por segundo; cada mensagem acima das 30 gratuitas por segundo custa 0,1 Telegram Star, cobrada só nos envios bem-sucedidos.

Por quanto tempo o Telegram guarda os updates de um bot?

Updates não entregues ficam guardados por até 24 horas. O getUpdates devolve no máximo 100 updates por chamada; confirme-os passando offset igual ao último update_id + 1.

Como criar um bot no Telegram grátis: do BotFather à primeira mensagem

Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.

Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless

Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.

Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais

Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.

Erros do Telegram Bot API: o que cada erro significa e como resolver

Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.

Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start

Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.

Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard

Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.

Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens

Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.

Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)

Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.

Telegram bot token: como pegar o token do bot, verificar e revogar

Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.

Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n

Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.

Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot

Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.

Bot inline no Telegram: como ativar o modo inline e responder às consultas

Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.

Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas

Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.

Servidor de teste do Telegram: como testar um bot no ambiente de teste

Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.

Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar

Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.

API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites

Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.

Exemplos de widget do Telegram: HTML completo e bot em Python

Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.

Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot

Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.

Como testar uma Mini App do Telegram: do mock no navegador ao app real

Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.