Webhook ou polling no bot do Telegram: qual usar

Todo bot do Telegram precisa receber as mensagens de algum jeito. A Bot API oferece dois: o bot pergunta ao Telegram se há novidades (long polling, método getUpdates) ou o Telegram avisa o bot por um POST HTTPS (webhook, método setWebhook). Os dois entregam o mesmo objeto Update; muda quem inicia a conversa.

Você usa um modo por vez. A escolha afeta onde o bot pode rodar, o que precisa estar aberto na rede e como ele se comporta sob carga. A própria documentação do Telegram diz que "não há nada de errado" em usar getUpdates, então não existe um modo obrigatório.

Como funciona o long polling?#

O bot chama getUpdates e o Telegram devolve até 100 atualizações pendentes (limit vai de 1 a 100). Com timeout maior que zero, o Telegram mantém a conexão aberta até chegar algo novo, em vez de responder vazio na hora. Com timeout igual a 0 (o padrão), é polling curto, que a documentação reserva para testes.

Para confirmar o que já foi processado, a chamada seguinte envia offset com o último update_id mais 1. As bibliotecas fazem isso sozinhas. Como a conexão sai do seu bot para o Telegram, não precisa de domínio, certificado nem porta aberta: funciona atrás de NAT, no notebook ou num container.

Como funciona o webhook?#

Você chama setWebhook com uma URL HTTPS e o Telegram passa a fazer um POST nela a cada atualização. Requisitos, segundo a documentação oficial:

• Porta 443, 80, 88 ou 8443. Outras portas não funcionam.
• TLS 1.2 ou superior. SSLv3, TLS 1.0 e TLS 1.1 não são aceitos.
• Certificado válido cujo CN ou SAN bate com o domínio, com os intermediários na cadeia. Certificado autoassinado é possível se você enviar a chave pública no parâmetro certificate.
• IPv4. O IPv6 não é suportado.
• Resposta com status 2XX. Com outro status, o Telegram tenta de novo e desiste depois de um número razoável de tentativas.

Parâmetros úteis: max_connections (de 1 a 100, padrão 40) controla quantas entregas simultâneas o Telegram faz; secret_token (1 a 256 caracteres, só letras, números, _ e -) volta no cabeçalho X-Telegram-Bot-Api-Secret-Token, e você deve rejeitar requisições sem ele. Para entender o certificado, veja como funciona o Let's Encrypt.

Qual a diferença na prática?#

Sobre desempenho, o Telegram é cauteloso: o webhook evita as requisições repetidas e o código de consulta, mas quanto isso muda no consumo de CPU ou no tempo de resposta depende do seu bot.

Quando escolher long polling?#

• Você está começando ou desenvolvendo no seu computador.
• O bot roda num ambiente sem domínio nem HTTPS próprio.
• O volume é pequeno ou médio, e um único processo dá conta.
• Você quer o menor número de peças que podem quebrar.

Quando escolher webhook?#

• Você já tem um servidor HTTPS com domínio, por exemplo uma API que também atende o bot.
• O volume é alto e você quer várias instâncias atrás de um balanceador.
• Seu ambiente só deve consumir recursos quando chega mensagem.
• Você quer o bot e outras rotas HTTP (painel, pagamentos) no mesmo processo web.

O Telegram limita o envio: considere cerca de uma mensagem por segundo num mesmo chat, 20 por minuto em grupos e uns 30 por segundo em envios em massa. O webhook não muda esses números.

Como trocar de um modo para o outro?#

Para ir de polling a webhook, basta configurar o webhook; a biblioteca faz a chamada. Para voltar, remova o webhook, ou o getUpdates vai falhar. Com curl e o token em variável de ambiente, o primeiro comando mostra o estado (url vazia significa sem webhook) e o segundo volta ao polling, descartando o que estava pendente:

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

curl "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook?drop_pending_updates=true"

Com a API do python-telegram-bot 22 (pip install "python-telegram-bot[webhooks]>=22,<23"), o mesmo handler serve nos dois modos; só muda a última chamada:

import os

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


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Olá!")


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))

    if os.environ.get("PUBLIC_URL"):
        app.run_webhook(
            listen="0.0.0.0",
            port=int(os.environ.get("PORT", "8080")),
            url_path="telegram",
            webhook_url=f"{os.environ['PUBLIC_URL']}/telegram",
            secret_token=os.environ["WEBHOOK_SECRET"],
        )
    else:
        app.run_polling()


if __name__ == "__main__":
    main()

Sem PUBLIC_URL o bot usa polling; com ela, webhook. Se o polling reclamar que há um webhook ativo, rode o deleteWebhook acima. Se o bot não responde de jeito nenhum, veja bot do Telegram não responde.

Como fazer isso na Square Cloud#

A Square Cloud é hospedagem self-service: você faz o deploy do bot e controla tudo no painel. Você pode usar python-telegram-bot, aiogram, Telethon, Telegraf ou grammY, com long polling sem configurar nada ou com um subdomínio HTTPS para webhooks.

Isso cobre os dois modos do código acima. Para polling, basta subir o bot. Para webhook, o bot passa a ser uma aplicação web: defina BOT_TOKEN, WEBHOOK_SECRET e PUBLIC_URL (com o subdomínio HTTPS da aplicação) nas variáveis de ambiente. O código já escuta em 0.0.0.0 na porta da variável PORT, que a plataforma define, então não há nada a ajustar. Nos dois modos o container fica sempre ligado, e o reinício automático (ligado por padrão no deploy pelo painel) traz o bot de volta quando o processo encerra com erro. Para manter o bot online, veja como hospedar um bot do Telegram 24/7.

Todos os planos são pagos e cobrados em reais. O Hobby custa R$ 12,49 por mês, com 1 GB de RAM compartilhado entre as suas aplicações. O mínimo por aplicação é de 256 MB para uma aplicação de fundo, como um bot em polling, e de 512 MB para uma aplicação web, como um bot com webhook. Veja a página de hospedagem de bots do Telegram.