La mejor librería para bots de Telegram: python-telegram-bot, aiogram, grammY o Telegraf

Todo bot de Telegram habla con la misma Bot API por HTTP. La librería que eliges no cambia lo que el bot puede hacer, pero cambia mucho la forma de llegar ahí: cómo registras comandos, guardas el estado de una conversación, programas tareas y sigues las novedades que Telegram publica varias veces al año.

Cuatro librerías aparecen con frecuencia en los tutoriales: python-telegram-bot y aiogram en Python, grammY y Telegraf en JavaScript. Abajo, cada una ejecuta el mismo bot de ejemplo para que compares el código.

¿Qué criterios importan al elegir?#

1. Lenguaje. Es el filtro más fuerte. Elige la librería del lenguaje que ya dominas, porque el resto del bot (base de datos, APIs, reglas de negocio) será mucho más grande que la parte de Telegram.
2. Compatibilidad con la Bot API. Telegram publica versiones nuevas de la Bot API a menudo, listadas en el changelog oficial. Una librería estancada no expone de forma nativa los tipos y métodos nuevos.
3. Ritmo de mantenimiento. Las versiones recientes indican que siguen llegando correcciones de bugs y de seguridad.
4. Funciones integradas. Conversaciones en varios pasos (máquina de estados), sesiones, tareas programadas, soporte de webhook y control del ritmo de envío. Lo que viene integrado es código que no escribes.
5. Documentación y comunidad. Si estás empezando, los ejemplos completos valen más que cualquier función avanzada.

La forma de recibir mensajes (long polling o webhook) no decide la elección: las cuatro soportan ambas. Con long polling el bot pregunta a Telegram por mensajes nuevos; con webhook, Telegram envía cada actualización por HTTPS a tu servidor. La diferencia está explicada en webhook vs long polling.

¿Cuándo elegir python-telegram-bot?#

python-telegram-bot es una de las librerías de Python más antiguas y conocidas para la Bot API. Desde la versión 20 está construida sobre asyncio. Exige una versión de Python que todavía tenga soporte (la mínima está en su documentación), y el soporte nativo de cada versión nueva de la Bot API suele llegar un tiempo después. Mientras tanto, las funciones más nuevas se pueden llamar a través de la API en bruto, como explica su propia documentación.

Un bot que responde a /start y repite lo que recibe (pip install python-telegram-bot):

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("¡Hola! Mándame un texto y lo repito.")


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(update.message.text)


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

Ventajas: documentación extensa, wiki y decenas de ejemplos; ConversationHandler para diálogos por pasos; persistencia integrada; JobQueue para tareas programadas y AIORateLimiter para respetar los límites de envío, ambos instalados como extras (python-telegram-bot[job-queue], [rate-limiter]).

Desventajas: el soporte nativo de las versiones nuevas de la Bot API suele llegar con retraso; las librerías que generan el código de la API automáticamente llegan antes. El modelo de handlers en orden y grupos exige cuidado cuando el bot crece.

¿Cuándo elegir aiogram?#

aiogram es una librería de Python totalmente asíncrona cuyo código de integración con la Bot API se genera automáticamente. Por eso suele seguir rápidamente las versiones nuevas de la Bot API. Las versiones de Python soportadas aparecen en su página de PyPI.

El mismo bot (pip install aiogram):

import asyncio
import os

from aiogram import Bot, Dispatcher, F
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("¡Hola! Mándame un texto y lo repito.")


@dp.message(F.text)
async def echo(message: Message) -> None:
    await message.answer(message.text)


async def main() -> None:
    bot = Bot(token=os.environ["BOT_TOKEN"])
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Ventajas: routers para dividir el bot en módulos, máquina de estados finita (FSM) integrada para formularios y conversaciones, middlewares, los "magic filters" (F.text, F.photo) y soporte de internacionalización. Encaja bien en bots grandes con muchos flujos.

Desventajas: exige sentirte cómodo con async/await y decoradores desde el primer día. La comunidad es fuerte, pero gran parte del material de terceros es de la antigua rama 2.x, cuya API es distinta de la 3.x.

¿Cuándo elegir grammY?#

grammY es una librería para JavaScript y TypeScript con versiones frecuentes, que suelen añadir cada versión nueva de la Bot API poco después de su lanzamiento. Funciona en Node.js y en Deno.

El mismo bot (npm install grammy, un archivo .mjs o "type": "module" en el package.json):

import { Bot } from "grammy";

const bot = new Bot(process.env.BOT_TOKEN);

bot.command("start", (ctx) => ctx.reply("¡Hola! Mándame un texto y lo repito."));
bot.on("message:text", (ctx) => ctx.reply(ctx.message.text));

bot.catch((err) => console.error("error en el update", err.error));
bot.start();

Ventajas: tipado TypeScript preciso (el filtro "message:text" garantiza que ctx.message.text existe), documentación muy didáctica en grammy.dev y un ecosistema de plugins oficiales: @grammyjs/conversations para diálogos, @grammyjs/menu para menús interactivos, @grammyjs/runner para procesar updates en paralelo con long polling y @grammyjs/auto-retry para reintentar peticiones que recibieron un 429. Las sesiones y los adaptadores de webhook para frameworks como Express vienen en el paquete principal.

Desventajas: muchas funciones están en plugins separados que tienes que conocer e instalar. Los tutoriales antiguos de JavaScript para Telegram suelen usar Telegraf o node-telegram-bot-api, no grammY.

¿Todavía vale la pena usar Telegraf?#

Telegraf fue durante años el estándar en Node.js y sigue funcionando. El problema es el ritmo: el paquete lleva bastante tiempo sin lanzamientos en npm, y su soporte declarado de la Bot API quedó varias versiones atrás. Revisa el historial de releases antes de adoptarlo. Los métodos más nuevos se pueden llamar con ctx.telegram.callApi, sin tipos.

El mismo bot (npm install telegraf):

import { Telegraf } from "telegraf";
import { message } from "telegraf/filters";

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => ctx.reply("¡Hola! Mándame un texto y lo repito."));
bot.on(message("text"), (ctx) => ctx.reply(ctx.message.text));

bot.launch();
process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

Ventajas: mucho material en internet, session y Scenes (escenas y wizards) en el propio paquete, una API parecida a la de grammY.

Desventajas: las funciones de la Bot API lanzadas después de su última versión no tienen tipos ni atajos. En un proyecto nuevo eso pesa. En un bot existente que solo usa mensajes, comandos y teclados, migrar no es urgente.

¿Cómo se comparan las cuatro lado a lado?#

Los límites de envío son los mismos para todas, porque vienen de Telegram: según el FAQ oficial, evita más de 1 mensaje por segundo en un chat, como máximo 20 por minuto en un grupo y unos 30 por segundo en envíos masivos. Si te pasas, recibes un error 429, el mismo tipo de límite que aplica Discord, explicado en error 429 y rate limit.

¿Cuál elegir en cada escenario?#

Si dudas, elige por el lenguaje y no por la librería. Un bot bien estructurado en cualquiera de las tres opciones activas cubre la mayoría de los casos. Después de elegir, el siguiente paso es dejar el proceso funcionando sin parar, como muestra cómo hospedar un bot de Telegram 24/7. Guarda el token en una variable de entorno, nunca en el código. Si el bot se queda mudo después del deploy, sigue el diagnóstico de bot de Telegram que no responde.

Cómo hacerlo en Square Cloud#

Square Cloud es hosting self-service para bots: tú haces el deploy y controlas la aplicación desde el panel. Soporta python-telegram-bot, aiogram, Telethon, Telegraf y grammY, con long polling sin configurar nada o un subdominio HTTPS para webhooks.

Cualquiera de los ejemplos de arriba funciona tal cual: define BOT_TOKEN en las variables de entorno de la aplicación y sube el proyecto en un ZIP, o haz el deploy con la CLI, GitHub o la extensión de VS Code. El archivo de configuración squarecloud.app es opcional: el panel lo genera en el deploy, y escribirlo en la raíz del proyecto es la alternativa. Los contenedores están siempre encendidos, con reinicio automático (activado por defecto en el deploy desde el panel) cuando el proceso termina con error.

Todos los planes son de pago y se cobran en reales. El Hobby empieza en R$12,49 al mes, con 1 GB de RAM compartido entre tus aplicaciones, y un bot, como aplicación en segundo plano, necesita al menos 256 MB. Mira el hosting de bots de Telegram.