Webhook o long polling en un bot de Telegram

Todo bot de Telegram tiene que recibir los mensajes de alguna forma. La Bot API ofrece dos: el bot le pregunta a Telegram si hay novedades (long polling, método getUpdates) o Telegram avisa al bot con un POST HTTPS (webhook, método setWebhook). Los dos entregan el mismo objeto Update; lo que cambia es quién inicia la conversación.

Usas un modo a la vez. La elección afecta dónde puede correr el bot, qué tiene que estar abierto en la red y cómo se comporta bajo carga. La propia documentación de Telegram dice que "no hay nada de malo" en usar getUpdates, así que ningún modo es obligatorio.

¿Cómo funciona el long polling?#

El bot llama a getUpdates y Telegram devuelve hasta 100 actualizaciones pendientes (limit va de 1 a 100). Con un timeout mayor que cero, Telegram mantiene la conexión abierta hasta que llega algo nuevo, en lugar de responder vacío al instante. Con timeout en 0 (el valor por defecto) es polling corto, que la documentación reserva para pruebas.

Para confirmar lo que ya procesaste, la llamada siguiente envía offset con el último update_id más 1. Las librerías lo hacen solas. Como la conexión sale de tu bot hacia Telegram, no necesitas dominio, certificado ni puerto abierto: funciona detrás de NAT, en una laptop o dentro de un contenedor.

¿Cómo funciona el webhook?#

Llamas a setWebhook con una URL HTTPS y Telegram empieza a enviar un POST a esa URL con cada actualización. Requisitos, según la documentación oficial:

• Puerto 443, 80, 88 u 8443. Otros puertos no funcionan.
• TLS 1.2 o superior. SSLv3, TLS 1.0 y TLS 1.1 no se aceptan.
• Un certificado válido cuyo CN o SAN coincida con el dominio, con los intermedios en la cadena. Un certificado autofirmado sirve si subes la clave pública en el parámetro certificate.
• IPv4. IPv6 no está soportado.
• Una respuesta con estado 2XX. Con cualquier otro estado, Telegram reintenta y se rinde tras un número razonable de intentos.

Parámetros útiles: max_connections (de 1 a 100, 40 por defecto) controla cuántas entregas simultáneas hace Telegram; secret_token (de 1 a 256 caracteres, solo letras, números, _ y -) vuelve en la cabecera X-Telegram-Bot-Api-Secret-Token, y debes rechazar las peticiones que no lo traigan. Para entender la parte del certificado, mira cómo funciona Let's Encrypt.

¿Cuál es la diferencia en la práctica?#

Sobre el rendimiento, Telegram es prudente: el webhook evita las peticiones repetidas y el código de consulta, pero cuánto cambia eso el uso de CPU o el tiempo de respuesta depende de tu bot.

¿Cuándo elegir long polling?#

• Estás empezando o desarrollas en tu propia computadora.
• El bot corre en un entorno sin dominio ni HTTPS propio.
• El volumen es pequeño o mediano y un solo proceso lo aguanta.
• Quieres la menor cantidad de piezas que se puedan romper.

¿Cuándo elegir webhook?#

• Ya tienes un servidor HTTPS con dominio, por ejemplo una API que también atiende al bot.
• El volumen es alto y quieres varias instancias detrás de un balanceador.
• Tu entorno solo debe consumir recursos cuando llega un mensaje.
• Quieres el bot y otras rutas HTTP (panel, pagos) en el mismo proceso web.

Ten en cuenta los límites de envío de Telegram: alrededor de un mensaje por segundo en un mismo chat, 20 por minuto en grupos y unos 30 por segundo en envíos masivos. El webhook no cambia esos números.

¿Cómo cambiar de un modo al otro?#

Para pasar de polling a webhook basta con configurar el webhook; la librería hace la llamada. Para volver, elimina el webhook, o getUpdates fallará. Con curl y el token en una variable de entorno, el primer comando muestra el estado (una url vacía significa que no hay webhook) y el segundo vuelve al polling, descartando lo que estuviera pendiente:

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

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

Con la API de python-telegram-bot 22 (pip install "python-telegram-bot[webhooks]>=22,<23"), el mismo handler sirve para los dos modos; solo cambia la última llamada:

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("¡Hola!")


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()

Sin PUBLIC_URL el bot usa polling; con ella, webhook. Si el polling se queja de que hay un webhook activo, ejecuta el deleteWebhook de arriba. Si el bot no responde de ninguna forma, mira el bot de Telegram no responde.

Cómo hacerlo en Square Cloud#

Square Cloud es hosting self-service: tú haces el deploy del bot y controlas todo desde el panel. Puedes usar python-telegram-bot, aiogram, Telethon, Telegraf o grammY, con long polling sin configurar nada o con un subdominio HTTPS para webhooks.

Eso cubre los dos modos del código de arriba. Para polling, basta con subir el bot. Para webhook, el bot pasa a ser una aplicación web: define BOT_TOKEN, WEBHOOK_SECRET y PUBLIC_URL (con el subdominio HTTPS de la aplicación) en sus variables de entorno. El código ya escucha en 0.0.0.0 en el puerto de la variable PORT, que define la plataforma, así que no hay nada que ajustar. En ambos modos el contenedor sigue encendido, y el reinicio automático (activado por defecto en el deploy desde el panel) vuelve a levantar el bot cuando el proceso termina con error. Para mantener el bot en línea, mira cómo alojar un bot de Telegram 24/7.

Todos los planes son de pago y se cobran en reales. El Hobby cuesta R$12,49 al mes, con 1 GB de RAM compartido entre tus aplicaciones. El mínimo por aplicación es de 256 MB para una aplicación en segundo plano, como un bot con polling, y de 512 MB para una aplicación web, como un bot con webhook. Consulta la página de hosting de bots de Telegram.