Melhor biblioteca para bot do Telegram: python-telegram-bot, aiogram, grammY ou Telegraf

Todo bot do Telegram conversa com a mesma Bot API por HTTP. A biblioteca que você escolhe não muda o que o bot pode fazer, mas muda muito o caminho até lá: como você registra comandos, guarda o estado de uma conversa, agenda tarefas e acompanha os recursos novos que o Telegram lança várias vezes por ano.

Quatro bibliotecas aparecem com frequência em tutoriais: python-telegram-bot e aiogram em Python, grammY e Telegraf em JavaScript. Abaixo, cada uma roda o mesmo bot de exemplo, para você comparar o código.

Quais critérios importam na escolha?#

1. Linguagem. É o filtro mais forte. Escolha a biblioteca da linguagem que você já domina, porque o código do bot (banco, APIs, regras de negócio) vai ser muito maior que a parte do Telegram.
2. Compatibilidade com a Bot API. O Telegram publica versões novas da Bot API com frequência, listadas no changelog oficial. Uma biblioteca parada não expõe os tipos e métodos novos de forma nativa.
3. Ritmo de manutenção. Releases recentes indicam que correções de bugs e de segurança continuam saindo.
4. Recursos prontos. Conversas em várias etapas (máquina de estados), sessões, agendamento de tarefas, suporte a webhook e controle de limite de envio. O que vem pronto é código que você não escreve.
5. Documentação e comunidade. Para quem está começando, exemplos completos valem mais que qualquer recurso avançado.

O modo de receber mensagens (long polling ou webhook) não decide a escolha: as quatro suportam os dois. A diferença está explicada em webhook vs long polling.

Quando escolher python-telegram-bot?#

python-telegram-bot é uma das bibliotecas Python mais antigas e conhecidas para a Bot API. Desde a versão 20 ela é construída sobre asyncio. Ela exige uma versão do Python ainda com suporte (a mínima está na documentação), e o suporte nativo a cada versão nova da Bot API costuma chegar algum tempo depois. Enquanto isso, recursos mais novos podem ser chamados pela API bruta, como a própria documentação explica.

Um bot que responde ao /start e repete o que recebe (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("Olá! Mande um texto que eu 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()

Prós: documentação extensa, wiki e dezenas de exemplos; ConversationHandler para diálogos em etapas; persistência embutida; JobQueue para tarefas agendadas e AIORateLimiter para respeitar limites de envio, ambos instalados como extras (python-telegram-bot[job-queue], [rate-limiter]).

Contras: o suporte nativo às versões novas da Bot API costuma atrasar; as bibliotecas que geram o código da API automaticamente chegam antes. O modelo de handlers em ordem e grupos exige atenção quando o bot cresce.

Quando escolher aiogram?#

aiogram é uma biblioteca Python totalmente assíncrona, com o código de integração da Bot API gerado automaticamente. Por isso ela costuma acompanhar as versões novas da Bot API rapidamente. As versões do Python suportadas estão na página do PyPI.

O mesmo 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("Olá! Mande um texto que eu 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())

Prós: roteadores para dividir o bot em módulos, máquina de estados finita (FSM) embutida para formulários e conversas, middlewares, os "magic filters" (F.text, F.photo) e suporte a internacionalização. É uma boa escolha para bots grandes, com muitos fluxos.

Contras: exige conforto com async/await e decorators desde o primeiro dia. A comunidade é forte, mas boa parte do material de terceiros é de versões antigas (2.x), cuja API é diferente da 3.x.

Quando escolher grammY?#

grammY é uma biblioteca para JavaScript e TypeScript com releases frequentes, que costumam acompanhar cada versão nova da Bot API pouco depois do lançamento. Roda em Node.js e em Deno.

O mesmo bot (npm install grammy, arquivo .mjs ou "type": "module" no package.json):

import { Bot } from "grammy";

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

bot.command("start", (ctx) => ctx.reply("Olá! Mande um texto que eu repito."));
bot.on("message:text", (ctx) => ctx.reply(ctx.message.text));

bot.catch((err) => console.error("erro no update", err.error));
bot.start();

Prós: tipagem TypeScript precisa (o filtro "message:text" garante que ctx.message.text existe), documentação muito didática em grammy.dev e um ecossistema de plugins oficiais: @grammyjs/conversations para diálogos, @grammyjs/menu para menus interativos, @grammyjs/runner para processar updates em paralelo com long polling e @grammyjs/auto-retry para repetir pedidos que levaram erro 429. Sessões e adaptadores de webhook para frameworks como Express vêm no pacote principal.

Contras: muitos recursos ficam em plugins separados, que você precisa conhecer e instalar. Tutoriais antigos de JavaScript para Telegram costumam usar Telegraf ou node-telegram-bot-api, não grammY.

Ainda vale a pena usar Telegraf?#

Telegraf foi por anos o padrão em Node.js e continua funcionando. O problema é o ritmo: o pacote está há bastante tempo sem lançamentos no npm, e o suporte declarado à Bot API ficou várias versões para trás. Confira o histórico de releases antes de adotar. Métodos mais novos ainda podem ser chamados com ctx.telegram.callApi, sem tipagem.

O mesmo 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("Olá! Mande um texto que eu 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"));

Prós: muito material na internet, session e Scenes (cenas e wizards) no próprio pacote, API parecida com a do grammY.

Contras: recursos da Bot API lançados depois da última release não têm tipos nem atalhos. Para um projeto novo, isso pesa. Para um bot existente que só usa mensagens, comandos e teclados, migrar não é urgente.

Como as quatro se comparam lado a lado?#

Os limites de envio são os mesmos para todas, porque vêm do Telegram: segundo o FAQ oficial, evite mais de 1 mensagem por segundo num chat, no máximo 20 por minuto num grupo e cerca de 30 por segundo em envios em massa. Passar disso gera erro 429, o mesmo tipo de limite que o Discord aplica, explicado em erro 429 e rate limit.

Qual escolher em cada cenário?#

Na dúvida, escolha pela linguagem e não pela biblioteca. Um bot bem estruturado em qualquer uma das três opções ativas atende a maioria dos casos. Depois de escolher, o próximo passo é deixar o processo rodando sem parar, como mostra como hospedar um bot do Telegram 24/7. Guarde o token numa variável de ambiente, nunca no código. Se o bot ficar mudo depois do deploy, siga o diagnóstico de bot do Telegram que não responde.

Como fazer isso na Square Cloud#

A Square Cloud é hospedagem self-service para bots: você faz o deploy e controla a aplicação pelo painel. Ela suporta python-telegram-bot, aiogram, Telethon, Telegraf e grammY, com long polling sem configurar nada ou um subdomínio HTTPS para webhooks.

Qualquer um dos exemplos acima roda como está: defina BOT_TOKEN nas variáveis de ambiente da aplicação e envie o projeto por upload de ZIP, CLI, GitHub ou extensão do VS Code. O arquivo de configuração squarecloud.app é opcional: o painel o gera no deploy, e escrevê-lo na raiz do projeto é a alternativa. Os containers ficam sempre ligados, com reinício automático (ligado por padrão no deploy pelo painel) quando o processo encerra com erro.

Todos os planos são pagos e cobrados em reais. O Hobby custa a partir de R$ 12,49 por mês, com 1 GB de RAM compartilhado entre as suas aplicações, e um bot, como aplicação de fundo, precisa de no mínimo 256 MB. Veja a hospedagem de bots do Telegram.