Telegram Bot API

Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes

· 6 min de lectura

Los límites de la Telegram Bot API parecen sencillos en papel: alrededor de 1 mensaje por segundo en un mismo chat, 20 mensajes por minuto en un grupo y unos 30 mensajes por segundo sumando todos los chats. Si los superas, la API responde 429 Too Many Requests con un valor retry_after. Esta página reúne todos los límites de la Telegram Bot API (ritmo de envío, envíos pagados, tamaño de archivos, longitud de textos y actualizaciones) con código que mantiene a tu bot dentro de ellos.

Rate limit de la Telegram Bot API para enviar mensajes

El Bots FAQ oficial indica estos límites para el envío normal y gratuito:

AlcanceLímiteNotas
Un chat≈ 1 mensaje por segundoSe toleran ráfagas cortas; después empiezan los errores 429.
Un grupo20 mensajes por minutoSe cuenta por cada chat de grupo.
Envíos masivos≈ 30 mensajes por segundoHasta 1000 por segundo con envíos pagados.

Toma estas cifras como referencia, no como contrato. Telegram advierte que los límites pueden cambiar, y en el entorno de prueba los límites de flood no son más altos (incluso pueden ser más estrictos). Un código que respeta retry_after sobrevive a cambios que romperían un "30" escrito a mano.

429 Too Many Requests y retry_after

Cuando alcanzas un límite de flood, la respuesta se ve así:

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

retry_after es la cantidad de segundos que faltan para poder repetir la petición. Espera al menos ese tiempo y envía la misma petición otra vez; reintentar de inmediato solo alarga el bloqueo. Una función auxiliar en Python o 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("sigue limitado, me rindo")

call("sendMessage", chat_id=123456789, text="Hola")
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("sigue limitado");
}

Regula los envíos masivos con una cola

Los reintentos resuelven peticiones sueltas. Para boletines y notificaciones tienes que regular el envío en sí, por ejemplo con un ritmo global un poco por debajo de 30 mensajes 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: el usuario bloqueó al bot, sácalo de la 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: el usuario bloqueó al bot, sácalo de la lista
    }
    await sleep(1000 / perSecond);
  }
}

En producción, ejecuta esto en un worker en segundo plano, guarda una marca de tiempo por chat para que ninguno reciba más de un mensaje por segundo y elimina los chats que devuelven 403 en lugar de reintentarlos. Sin envíos pagados, Telegram recomienda repartir los envíos grandes en intervalos más largos, por ejemplo de 8 a 12 horas.

Si 30 mensajes por segundo no te alcanzan, activa los envíos pagados (paid broadcasts) en @BotFather y pasa "allow_paid_broadcast": true a métodos de envío como sendMessage, sendPhoto o sendMediaGroup. Así el bot puede enviar hasta 1000 mensajes por segundo. Cada mensaje por encima de los 30 gratuitos por segundo cuesta 0,1 Telegram Stars del saldo del bot, y solo se cobran los mensajes enviados con éxito. Para usarlo se necesita un saldo mínimo de Stars (el Bots FAQ también menciona un umbral de audiencia), así que revisa las cifras actuales en la documentación oficial antes de planear con esto.

Límites de tamaño de archivo de los bots de Telegram

OperaciónLímite
Subir un archivo con multipart/form-data50 MB
Subir una foto10 MB; ancho + alto ≤ 10000, relación de aspecto ≤ 20
Enviar una foto por URL HTTP5 MB
Enviar otros archivos por URL HTTP20 MB (sendDocument por URL solo funciona con .PDF y .ZIP)
Descargar con getFile20 MB; el enlace de descarga es válido al menos 1 hora
Reenviar por file_idSin límite de tamaño

Un servidor local de Bot API elimina las dos restricciones más grandes: subidas de hasta 2000 MB y descargas sin límite de tamaño, además de webhooks por HTTP plano en cualquier puerto. Llama a logOut antes de apuntar el bot a tu propio servidor. Para revisar un archivo antes de descargarlo, llama a getFile en Bot API Tester y mira file_size y file_path.

Longitud de mensajes y otros límites de contenido

ElementoLímite
Texto del mensaje1–4096 caracteres después de procesar las entidades
Descripción (caption) de multimedia0–1024 caracteres
Rich message (sendRichMessage)32768 caracteres UTF-8, 500 bloques, 50 archivos multimedia, 20 columnas de tabla
callback_data1–64 bytes
Grupo de medios (media group)2–10 elementos
Respuesta a una consulta inlineHasta 50 resultados
Texto de answerCallbackQuery0–200 caracteres
setMyCommands100 comandos; comando de 1–32 caracteres, descripción de 1–256
Parámetro start del deep linkHasta 64 caracteres: A-Z a-z 0-9 _ -
sendData de Mini AppHasta 4096 bytes

callback_data se cuenta en bytes, y los caracteres fuera de ASCII (como á, ñ o los emojis) ocupan de 2 a 4 bytes en UTF-8, así que guarda un id corto en el botón y deja los detalles en tu base de datos. Los textos de más de 4096 caracteres deben dividirse, de preferencia en los saltos de línea:

def split_text(text, limit=4000):  # un poco menos de 4096 por seguridad
    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) { // un poco menos de 4096 por seguridad
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // divide en líneas, conserva "\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;
}

Límites de actualizaciones y del webhook

Cómo mantenerte dentro de los límites de la Telegram Bot API

Guías relacionadas: enviar mensajes con la Bot API trata el formato y los errores de cada mensaje, configurar un webhook explica cómo recibir actualizaciones a gran escala y las novedades de Bot API 10 presenta los rich messages y sus límites.

Preguntas frecuentes

¿Cuál es el rate limit de la Telegram Bot API?

El Bots FAQ de Telegram da tres cifras: evita más de 1 mensaje por segundo en un mismo chat, no envíes más de 20 mensajes por minuto en un grupo y unos 30 mensajes por segundo para envíos masivos. Si los superas, recibes 429 Too Many Requests.

¿Cómo soluciono 429 Too Many Requests en Telegram?

Lee parameters.retry_after del error, espera esa cantidad de segundos y repite la misma petición. Para no volver a chocar con el límite, envía a través de una cola que regule el ritmo por chat y en total.

¿Cuál es el límite de tamaño de archivo de un bot de Telegram?

Los bots pueden subir archivos de hasta 50 MB (fotos de hasta 10 MB) y descargar archivos de hasta 20 MB con getFile. El envío por URL está limitado a 5 MB para fotos y 20 MB para otros archivos. Un servidor local de Bot API permite subir hasta 2000 MB y descargar sin límite de tamaño.

¿Qué tan largo puede ser un mensaje de un bot de Telegram?

Un mensaje de texto admite 1–4096 caracteres después de procesar las entidades y la descripción de un archivo multimedia, 0–1024 caracteres, así que los textos más largos hay que dividirlos. Los rich messages (Bot API 10.1+) permiten hasta 32768 caracteres UTF-8.

¿Cómo puede un bot de Telegram enviar más de 30 mensajes por segundo?

Activa los envíos pagados en @BotFather y pasa allow_paid_broadcast: true. El bot podrá enviar hasta 1000 mensajes por segundo; cada mensaje por encima de los 30 gratuitos por segundo cuesta 0,1 Telegram Stars y solo se cobran los envíos exitosos.

¿Cuánto tiempo guarda Telegram las actualizaciones de un bot?

Las actualizaciones no entregadas se guardan hasta 24 horas. getUpdates devuelve como máximo 100 actualizaciones por llamada; confírmalas pasando offset igual al último update_id + 1.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless

Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.

Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más

Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.

Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start

Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.

Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard

Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Bot inline de Telegram: cómo activar el modo inline y responder consultas

Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.

Cómo probar una Mini App de Telegram: del navegador a Telegram real

Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.