Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens
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:
| Escopo | Limite | Observações |
|---|---|---|
| Um chat | ≈ 1 mensagem por segundo | Picos curtos são tolerados; depois começam os erros 429. |
| Um grupo | 20 mensagens por minuto | Contado por grupo. |
| Envios em massa | ≈ 30 mensagens por segundo | Até 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.
Paid broadcasts: até 1000 mensagens por segundo
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ção | Limite |
|---|---|
Upload de arquivo com multipart/form-data | 50 MB |
| Upload de foto | 10 MB; largura + altura ≤ 10000, proporção ≤ 20 |
| Enviar foto por URL HTTP | 5 MB |
| Enviar outros arquivos por URL HTTP | 20 MB (sendDocument por URL só funciona com .PDF e .ZIP) |
Download com getFile | 20 MB; o link de download vale por pelo menos 1 hora |
Reenviar por file_id | Sem 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
| Item | Limite |
|---|---|
| Texto da mensagem | 1–4096 caracteres depois do parse das entidades |
| Legenda de mídia | 0–1024 caracteres |
Rich message (sendRichMessage) | 32768 caracteres UTF-8, 500 blocos, 50 mídias, 20 colunas de tabela |
callback_data | 1–64 bytes |
| Grupo de mídia | 2–10 itens |
| Resposta a inline query | Até 50 resultados |
Texto do answerCallbackQuery | 0–200 caracteres |
setMyCommands | 100 comandos; comando com 1–32 caracteres, descrição com 1–256 |
Parâmetro start de deep link | Até 64 caracteres: A-Z a-z 0-9 _ - |
sendData da Mini App | Até 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 partsfunction 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
- Os updates recebidos ficam nos servidores do Telegram por até 24 horas, até o bot buscá-los.
getUpdatesdevolve 1–100 updates por chamada (limit, padrão 100). Usetimeoutpara long polling e confirme os updates comoffset= últimoupdate_id+ 1.getUpdatesnão funciona enquanto houver webhook configurado (409 Conflict), até você chamardeleteWebhook.setWebhookaceitamax_connectionsde 1 a 100 (padrão 40) e só as portas 443, 80, 88 e 8443. Um servidor local do Bot API permite até 100000 conexões e qualquer porta.
Como ficar dentro dos limites do Telegram Bot API
- Envie tudo por uma única fila, com taxa global abaixo de 30 por segundo e no máximo uma mensagem por segundo por chat.
- Mostre progresso editando uma mensagem com
editMessageTextem vez de postar várias novas. - Reenvie mídias por
file_idem vez de fazer upload de novo. - Respeite o
retry_aftere nunca repita requisições que deram 403. - Passe
allowed_updatespara receber só os tipos de update que você realmente trata.
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.
Guias relacionados
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.