Bot de Telegram no responde: webhook, polling y errores comunes

Cuando un bot de Telegram se queda mudo, no aparece ninguna pantalla roja que diga por qué. Telegram entrega los updates por HTTP, así que el silencio puede venir de tres lugares: el token, tu proceso o el camino entre Telegram y tu proceso (polling o webhook). Si se lo preguntas a la propia API, averiguas cuál es en dos minutos.

El orden que más tiempo ahorra es este: validar el token, ver cómo llegan los updates y solo entonces revisar las causas concretas. Para la base de cómo recibe updates un bot, consulta cómo alojar un bot de Telegram 24/7.

¿Cómo descubres dónde está el problema?#

Define el token en una variable de entorno (nunca lo pegues en un chat ni en un repositorio) y ejecuta este script. Solo usa la biblioteca estándar de Python:

import json
import os
import urllib.request

TOKEN = os.environ["BOT_TOKEN"]


def call(method: str) -> dict:
    url = f"https://api.telegram.org/bot{TOKEN}/{method}"
    with urllib.request.urlopen(url, timeout=10) as r:
        return json.load(r)


print("getMe:", call("getMe"))
print("getWebhookInfo:", call("getWebhookInfo"))

Interpreta el resultado así:

• getMe da error 401 Unauthorized: el token está mal o fue revocado. Nada más importa hasta corregirlo.
• getWebhookInfo con url definida: el bot está en modo webhook. Mira pending_update_count (updates esperando entrega), last_error_date y last_error_message (el último error al entregar).
• url vacía: el bot debería estar en polling. Si no responde, el problema es el proceso o un conflicto de instancias.

Si getMe funciona y el proceso está corriendo pero no llega nada, sigue con las secciones de abajo. El log del proceso casi siempre completa el cuadro.

¿El problema está en el token o en el proceso?#

Son las dos causas más fáciles de revisar, así que conviene descartarlas primero.

¿El token es correcto?#

Un 401 viene de un token erróneo, copiado con un espacio de más o revocado. La revocación ocurre cuando generas un token nuevo en @BotFather (el anterior deja de valer) o cuando revocas un token filtrado. Verifica que la variable de entorno del servidor tenga el valor actual, sin comillas ni saltos de línea. Para el concepto, lee qué son las variables de entorno.

¿El proceso está corriendo?#

Parece obvio, pero es una de las causas más comunes: el bot corría en tu computadora y la computadora se suspendió, se reinició o perdió la conexión. En un servidor, el proceso puede haberse caído por un error no controlado o por falta de memoria. Busca en el log la última excepción antes del silencio y verifica si hay reinicio automático. El artículo sobre monitorear el uptime de un bot explica cómo enterarte antes que tus usuarios.

Si el bot estuvo caído, los updates no se pierden al instante: Telegram guarda los pendientes hasta que el bot los recoge, por un máximo de 24 horas.

¿Por qué aparece "Conflict: terminated by other getUpdates request"?#

telegram.error.Conflict: Conflict: terminated by other getUpdates request;
make sure that only one bot instance is running

Solo puede existir una conexión de getUpdates por bot. Si dos instancias hacen polling con el mismo token, una desconecta a la otra, y el comportamiento se vuelve intermitente: a veces responde y a veces no. Los orígenes más comunes:

• el bot todavía corriendo en tu PC, olvidado en una terminal;
• un deploy nuevo que arrancó antes de que el antiguo se detuviera;
• dos contenedores o réplicas del mismo servicio.

La solución es dejar una única instancia por token. Si quieres separar desarrollo y producción, crea dos bots en @BotFather, cada uno con su token.

¿El webhook y el polling se están peleando?#

Un bot usa un método cada vez. Mientras haya un webhook configurado, getUpdates no recibe nada. El caso clásico: probaste un webhook, después hiciste el deploy del código en polling y el bot se quedó callado. getWebhookInfo muestra la url todavía registrada. Elimínala:

curl "https://api.telegram.org/bot${BOT_TOKEN}/deleteWebhook"

Lo contrario también vale: después de un setWebhook, el polling deja de funcionar. Para descartar la cola acumulada al cambiar de método, pasa drop_pending_updates a deleteWebhook o a setWebhook.

¿Por qué el webhook no entrega updates?#

Cuando aparece last_error_message en getWebhookInfo, Telegram intentó entregar y falló. Revisa, en este orden:

1. HTTPS válido. No existe webhook en HTTP plano, y Telegram exige TLS 1.2 o superior. Un certificado vencido, un dominio distinto al del certificado o una cadena sin el certificado intermedio causan errores de SSL. Consulta también errores de certificado SSL.
2. Puerto permitido. Solo 443, 80, 88 y 8443.
3. Accesible desde fuera. El servidor tiene que ser alcanzable por su dirección pública. Un firewall que bloquea el puerto, o el proceso escuchando solo en 127.0.0.1, impide la entrega. Telegram envía desde rangos IPv4 (149.154.160.0/20 y 91.108.4.0/22); IPv6 no está soportado en webhooks.
4. Secreto coincidente. Si definiste secret_token (de 1 a 256 caracteres), Telegram lo envía en el encabezado X-Telegram-Bot-Api-Secret-Token. Si tu código rechaza la solicitud porque ese encabezado no coincide, el bot parece mudo.
5. Respuesta rápida. Responde con 200 enseguida y procesa el trabajo pesado en segundo plano. Un handler que se bloquea o lanza un error deja a Telegram sin respuesta.

Después de corregirlo, llama de nuevo a getWebhookInfo: pending_update_count debería bajar y last_error_message debería dejar de cambiar.

¿El bot funciona en privado pero no en grupos?#

Es el privacy mode, activado por defecto. Con él, el bot en un grupo solo recibe comandos dirigidos a él (como /ayuda@mi_bot) y respuestas a sus mensajes. Los mensajes normales del grupo no llegan. Hay dos salidas: desactivarlo con /setprivacy en @BotFather (después quita el bot del grupo y vuelve a agregarlo para que el cambio aplique) o promover el bot a administrador del grupo.

¿El bot deja de responder solo bajo carga?#

Puede ser un límite de envío. La FAQ de Telegram recomienda no pasar de alrededor de un mensaje por segundo en el mismo chat, y los bots no pueden enviar más de 20 mensajes por minuto en un grupo. En envíos masivos, el límite es de unos 30 mensajes por segundo, salvo que el bot active las difusiones de pago de Telegram. Por encima de eso, la API responde 429 y los mensajes del bot fallan. Usa una cola que espacie los envíos y maneja el error 429 en lugar de reintentar en bucle.

¿Cómo evitas que vuelva a pasar?#

• Una instancia por token y variables de entorno en el servidor, no en el código.
• Logs accesibles y una alerta externa de disponibilidad.
• Reinicio automático del proceso.
• Un comando /ping en el bot y, con webhook, un vistazo periódico a last_error_message.

Cómo hacerlo en Square Cloud#

Varias causas de esta lista (proceso detenido, variable de entorno equivocada, un log que nadie lee) dependen de dónde corre el bot. Square Cloud es hosting self-service: tú haces el deploy del bot, defines la memoria y controlas todo desde el panel. Soporta python-telegram-bot, aiogram, Telethon, Telegraf y grammY, con long polling sin configuración o un subdominio HTTPS para webhooks.

Los contenedores están siempre encendidos, sin modo de suspensión, y el reinicio automático (activado por defecto en el deploy desde el panel) trae el bot de vuelta cuando el proceso termina con error. Las variables de entorno (como BOT_TOKEN) se definen por aplicación y se aplican en el siguiente reinicio. Los logs en tiempo real muestran el Conflict o el error que derribó el proceso.

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, y el mínimo para una aplicación en segundo plano como un bot es de 256 MB. Los detalles están en la página de hosting de bots de Telegram.