Telegram Bot API a través de proxy: configuración de long polling, webhooks y manejo del error 429

Introducción: qué obtendrás con esta guía

Si alguna vez has lanzado un bot en Telegram, conoces esa situación desagradable. El bot se escribe en una tarde, pero su funcionamiento estable se convierte en un proyecto aparte. Los mensajes llegan con retraso, las actualizaciones se pierden, el servidor de repente recibe un error 429 y el webhook simplemente deja de invocarse sin explicación. Súmale un proxy por el que deben pasar todas las peticiones y la cantidad de puntos de fallo se duplica.

Esta guía paso a paso resuelve exactamente esos problemas. Aprenderás a trabajar con Telegram Bot API a través de un servidor proxy para que el bot no se caiga, no pierda mensajes y reaccione correctamente a los límites. No vamos a analizar el protocolo MTProto ni a construir un sistema de monitoreo de proxies. Nuestro tema es más concreto y práctico: peticiones HTTP a api.telegram.org a través de proxy, dos formas de recibir actualizaciones y la reacción correcta ante las restricciones.

Qué obtendrás al final

• Un bot funcional que envía peticiones a Telegram Bot API a través de tu proxy (HTTP o SOCKS5).
• Un long polling configurado que no se corta por timeouts y no duplica mensajes.
• Un webhook con HTTPS y token secreto que recibe actualizaciones en tu servidor.
• Un envoltorio listo para las peticiones que espera el tiempo necesario ante un error 429 y reintenta el envío.
• Entender qué modo elegir para tu proyecto: polling o webhook.

Para quién es esta guía

Para marketers y especialistas en arbitraje que arman bots para envíos masivos, notificaciones de leads y estadísticas de campañas. Para desarrolladores que necesitan una IP de salida fija y predecible para las peticiones del servidor. Para dueños de negocios cuyos bots atienden clientes y no pueden permitirse estar en silencio durante una hora. Si trabajas con proxies móviles y quieres pasar por ellos el tráfico del bot, llegaste al lugar correcto.

Qué necesitas saber de antemano

Explicamos cada paso desde cero, pero algunas habilidades básicas te facilitarán mucho la vida. Es útil saber abrir una terminal o línea de comandos, copiar comandos y ejecutar scripts en Python. Saber qué es una petición HTTP y JSON es deseable, pero lo recordaremos en palabras simples. Los temas avanzados están en una sección aparte, los principiantes pueden saltársela sin perder el resultado.

Cuánto tiempo tomará

La preparación y creación del bot tomarán unos 20 minutos. La configuración del proxy y la primera petición exitosa otros 20-30 minutos. El long polling lo lanzarás en media hora. El webhook requerirá 40-60 minutos, porque necesitas un certificado HTTPS. El manejo del error 429 añadirá otros 20 minutos. En total, entre dos y tres horas de trabajo tranquilo con verificaciones en cada etapa.

Preparación previa: herramientas y accesos

Antes de escribir la primera línea de código, reunamos todo lo necesario. Así no te interrumpirás en medio de un paso buscando dónde conseguir la contraseña del proxy o cómo instalar una librería.

Herramientas y accesos necesarios

1. Cuenta de Telegram con número vinculado. Desde ella crearás el bot a través del bot oficial BotFather.
2. Acceso al proxy: dirección del servidor, puerto, usuario y contraseña. En el panel de mobileproxy.space estos datos aparecen en la tarjeta del proxy comprado. Normalmente hay dos puertos disponibles: uno para conexión HTTP y otro para SOCKS5. Anota ambos.
3. Computadora o servidor con Python 3.10 o superior instalado. Para el webhook necesitarás un servidor con IP pública y dominio; en una computadora de casa el webhook no funcionará.
4. La utilidad curl. En Windows 10 y 11, macOS y Linux ya viene integrada. Verifícala con el comando curl --version.
5. Editor de texto: VS Code, Notepad++ o cualquiera donde te sea cómodo escribir código.

Requisitos del sistema

Para el polling casi no hay requisitos: cualquier máquina con acceso a internet, incluida una laptop. El bot consume unas pocas decenas de megabytes de memoria. Para el webhook necesitas un VPS con configuración mínima: 1 núcleo, 1 GB de RAM, Ubuntu 22.04 o 24.04. Es obligatorio un dominio apuntando a la IP de ese servidor y el puerto 443 abierto en el firewall.

Qué instalar

1. Abre la terminal.
2. Verifica Python con el comando python3 --version. En Windows el comando puede ser python --version.
3. Crea la carpeta del proyecto: mkdir tgbot-proxy, luego entra en ella cd tgbot-proxy.
4. Crea un entorno virtual: python3 -m venv venv. Actívalo: en Linux y macOS source venv/bin/activate, en Windows venv\Scripts\activate.
5. Instala las librerías: pip install requests[socks] flask. El paquete requests se encarga de las peticiones a Telegram Bot API, el complemento socks es necesario para proxy por protocolo SOCKS5, y Flask recibirá el webhook.

Copias de seguridad y seguridad de datos

Trata el token del bot como la contraseña de tu app bancaria. Quien lo obtenga podrá escribir en nombre del bot a tus clientes. Crea un archivo .env con el token y los datos del proxy y nunca lo subas a un repositorio público. Si el bot ya está funcionando y lo migras a proxy, guarda la configuración actual, haz un respaldo de la base de datos si existe y anota el resultado del método getWebhookInfo. Así el rollback tomará dos minutos.

Consejo: Crea un bot de prueba aparte para experimentar. Practica todos los pasos de esta guía primero con él y pasa al bot de producción solo la configuración ya verificada. Así no romperás la comunicación con clientes reales.

Conceptos básicos: cómo está estructurado Telegram Bot API

Analicemos los términos clave en palabras simples. Sin ellos, los siguientes pasos parecerán magia; con ellos, se volverán lógicos y predecibles.

Telegram Bot API

Es una interfaz HTTP común. Tu código envía una petición a una dirección del tipo https://api.telegram.org/bot<ТОКЕН>/<метод>, y el servidor de Telegram responde con un objeto JSON. Por ejemplo, el método getMe devuelve información del bot, y sendMessage envía texto a un chat. No necesitas librerías especiales, basta con curl o requests. Precisamente por eso Telegram Bot API es tan fácil de pasar por proxy: es el mismo tráfico que el de cualquier sitio por HTTPS.

Actualizaciones (updates)

Cada evento para el bot, ya sea un mensaje, una pulsación de botón o una adición a un grupo, llega como un objeto update con un número único update_id. Los números crecen en orden. La tarea de tu código es recibir esos objetos y procesarlos. Hay exactamente dos formas de recibirlos, y son mutuamente excluyentes.

Long polling

Tu bot pregunta él mismo a Telegram: ¿hay actualizaciones nuevas para mí? Lo hace con el método getUpdates. La palabra «long» significa que el servidor no responde al instante con una lista vacía, sino que mantiene la conexión abierta hasta el timeout indicado, normalmente 30-60 segundos, y responde en cuanto aparece un evento. Esto ahorra peticiones y da una reacción casi instantánea. El polling no requiere dirección pública, funciona detrás de un router y a través de cualquier proxy. Es ideal para empezar y para bots con poca carga.

Webhook

El enfoque inverso. Le comunicas a Telegram la dirección de tu servidor con el método setWebhook, y Telegram envía cada actualización mediante una petición POST a esa dirección. No necesitas consultar nada. Requisitos: dominio público, certificado HTTPS y uno de los puertos 443, 80, 88 u 8443. El webhook escala mejor y no gasta recursos en esperar.

Importante: el proxy solo influye en las peticiones salientes de tu bot hacia Telegram. Las peticiones entrantes del webhook llegan directamente a tu servidor, y el proxy no participa en esa cadena. Por eso la frase «webhook a través de proxy» en la práctica significa: el bot responde y llama a los métodos de la API a través del proxy, y recibe las actualizaciones en su propia dirección pública.

Error 429 Too Many Requests

Telegram limita la frecuencia de peticiones. Referencias para 2026: no más de un mensaje por segundo en un chat, no más de 20 mensajes por minuto en un grupo y alrededor de 30 mensajes por segundo en total por bot. Al excederlo, el servidor devuelve el estado HTTP 429 y en el cuerpo de la respuesta el campo parameters.retry_after con la cantidad de segundos de espera. Ignorarlo no es opción: los reintentos sin pausa aumentan el tiempo de bloqueo.

Para qué sirve un proxy en un bot

Las razones son puramente prácticas. Primero, una IP de salida fija y predecible: es útil cuando hay muchos servidores pero se necesita una única dirección externa. Segundo, separar el tráfico por proyectos: cada cliente o cada campaña con su propio canal. Tercero, políticas corporativas, cuando todas las conexiones externas deben pasar por un gateway. Los proxies móviles aquí valen por su estabilidad y la posibilidad de gestionar el cambio de IP por programación o por enlace.

Paso 1: Creamos el bot y obtenemos el token

Objetivo de la etapa: obtener el token de acceso a Telegram Bot API y asegurarte de que el bot existe.

1. Abre Telegram en el teléfono o la computadora.
2. En la barra de búsqueda escribe BotFather. Elige el bot con la palomita azul de verificación, los falsos no la tienen.
3. Pulsa el botón Start o envía el comando /start. Verás una lista de comandos disponibles.
4. Envía el comando /newbot.
5. BotFather te pedirá el nombre del bot. Escribe el nombre visible, por ejemplo Proxy Test Bot. Puede contener espacios y caracteres especiales.
6. Luego te pedirá el username. Debe ser único, en latín y terminar en bot, por ejemplo proxy_test_2026_bot. Si el nombre está ocupado, BotFather te lo dirá, inventa otro.
7. En respuesta recibirás un mensaje de felicitación con una línea del tipo 123456789:AAExampleTokenLettersAndDigits. Ese es el token. Cópialo completo, incluyendo los dígitos antes de los dos puntos.
8. Crea en la carpeta del proyecto el archivo .env y escribe en él la línea BOT_TOKEN=tu_token.

Atención: Nunca publiques el token en chats, capturas de pantalla ni repositorios abiertos. Si el token se filtró, envía de inmediato a BotFather el comando /revoke, elige el bot y obtén un token nuevo. El anterior dejará de funcionar al instante.

Primera petición sin proxy

Antes de complicar el esquema, verifiquemos que el token funciona con una petición normal desde tu máquina. Ejecuta en la terminal, sustituyendo tu token:

curl https://api.telegram.org/bot123456789:AAExampleToken/getMe

Respuesta esperada: un JSON que empieza con {"ok":true,"result":{"id":123456789,"is_bot":true,.... Dentro verás el username del bot que acabas de crear.

Verificación: En la respuesta hay "ok":true y el username correcto. Si en su lugar llegó "error_code":401, el token se copió con error, revisa que no se hayan perdido caracteres en los extremos.

Posibles problemas

• Username ocupado. Añade dígitos o una abreviatura del proyecto, lo importante es conservar la terminación bot.
• BotFather no responde. Asegúrate de haber abierto el bot con la palomita de verificación, no un homónimo.
• Error 404 Not Found. Falta la palabra bot antes del token en la dirección. El formato es estrictamente /bot<ТОКЕН>/método.

Paso 2: Conectamos el proxy y verificamos el acceso a la API

Objetivo de la etapa: hacer que las peticiones a Telegram Bot API pasen por tu proxy y verificarlo de hecho, no de palabra.

Entendemos el formato de la dirección del proxy

El proxy se describe con una sola línea: protocolo://usuario:contraseña@host:puerto. Toma los datos del panel. Supongamos que te dieron el host proxy-host, puerto HTTP 8080, puerto SOCKS5 1080, usuario user y contraseña pass. Entonces las líneas serán así:

• Proxy HTTP: http://user:pass@proxy-host:8080
• Proxy SOCKS5: socks5h://user:pass@proxy-host:1080

Fíjate en la letra h en socks5h. Significa que el nombre de dominio api.telegram.org se resolverá del lado del proxy, no en tu máquina. Esta es la variante correcta para proxies móviles: las consultas DNS y el tráfico van por la misma ruta. Sin la letra h, si hay problemas con el DNS local, las peticiones fallarán aunque el proxy esté en buen estado.

Si en la contraseña hay símbolos @, : o /, hay que codificarlos: @ se convierte en %40, los dos puntos en %3A, la barra en %2F. De lo contrario la línea se interpretará mal.

Verificación con curl

1. Primero averigua qué IP ven los servicios externos a través de tu proxy. Ejecuta: curl -x http://user:pass@proxy-host:8080 https://api.ipify.org. En respuesta llegará la dirección IP. Debe ser distinta de tu dirección doméstica o del servidor.
2. Ahora la misma petición a Telegram Bot API: curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
3. Para SOCKS5 cambia el parámetro: curl -x socks5h://user:pass@proxy-host:1080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
4. Mide el tiempo de respuesta: añade al final del comando -w " tiempo: %{time_total}". Un valor de hasta 1-2 segundos para un proxy móvil es normal.

Verificación: Ambas peticiones devolvieron "ok":true, y la IP del primer comando es distinta de la tuya. Esto significa que la ruta a través del proxy funciona y Telegram Bot API responde por ella.

Configuramos el proxy en Python

Crea el archivo config.py con el siguiente contenido, reemplazando los valores por los tuyos:

import os
TOKEN = os.getenv('BOT_TOKEN', '123456789:AAExampleTokenReplaceMe')
PROXY = os.getenv('BOT_PROXY', 'http://user:pass@proxy-host:8080')
PROXIES = {'http': PROXY, 'https': PROXY}
BASE = f'https://api.telegram.org/bot{TOKEN}'

La clave https en el diccionario es obligatoria, porque Telegram Bot API trabaja solo por HTTPS. Un error frecuente de principiantes es indicar solo http y sorprenderse de que el tráfico vaya directo.

Ahora el script de prueba check.py:

import requests
from config import PROXIES, BASE
ip = requests.get('https://api.ipify.org', proxies=PROXIES, timeout=15).text
print('Исходящий IP:', ip)
me = requests.get(f'{BASE}/getMe', proxies=PROXIES, timeout=15).json()
print('Бот:', me['result']['username'])

Ejecuta: python check.py. En pantalla aparecerán la IP del proxy y el username del bot.

Consejo: Si no quieres modificar el código de la librería que ya usas, define la variable de entorno HTTPS_PROXY=http://user:pass@proxy-host:8080. La librería requests y la mayoría de los clientes HTTP la toman automáticamente. Es una forma cómoda de migrar un bot existente a proxy sin cambios.

Configuración en frameworks populares

• aiogram 3.x: crea la sesión AiohttpSession(proxy='http://user:pass@proxy-host:8080') y pásala al crear el objeto Bot(token=TOKEN, session=session). Para SOCKS5 necesitarás el paquete aiohttp-socks.
• python-telegram-bot 21.x: usa HTTPXRequest(proxy='http://user:pass@proxy-host:8080') y pásalo a ApplicationBuilder().token(TOKEN).request(request).
• Node.js: el paquete https-proxy-agent o socks-proxy-agent crea un agente que se pasa en las opciones del cliente HTTP o en el constructor de la librería del bot.

Posibles problemas

• 407 Proxy Authentication Required. Usuario o contraseña incorrectos, o caracteres especiales sin codificar. Verifica los datos en el panel.
• Connection refused. El puerto está mal indicado o se confundieron los puertos HTTP y SOCKS5. Prueba el segundo puerto.
• La petición va directa. Falta la clave https en el diccionario o la variable de entorno está definida en otra ventana de la terminal.
• Error SSL. No desactives la verificación del certificado. Actualiza el paquete certifi con pip install -U certifi y revisa la hora del sistema.

Paso 3: Lanzamos long polling a través del proxy

Objetivo de la etapa: obtener un bot funcional que a través del proxy recoge actualizaciones con el método getUpdates y responde a los mensajes sin perderlos ni duplicarlos.

Cómo construir correctamente el ciclo de polling

La lógica es simple, pero los detalles importan. Llamas a getUpdates con el parámetro offset igual al último update_id procesado más uno. Así Telegram entiende que las actualizaciones anteriores fueron recibidas y las elimina de su lado. Si olvidas el offset, el mismo mensaje llegará una y otra vez, y el bot empezará a responder varias veces.

El parámetro timeout define cuántos segundos mantiene el servidor la conexión esperando eventos. Aquí empieza la especificidad del proxy. Todo proxy tiene su propio timeout de conexión inactiva; en los proxies móviles suele rondar los 60-120 segundos. Si el timeout del polling es mayor, el proxy cortará la conexión antes de que responda Telegram y recibirás un error en lugar de actualizaciones. El valor seguro es timeout=50 con un timeout del cliente HTTP de 60 segundos. El timeout del cliente siempre debe ser mayor que el del polling, de lo contrario el cliente se caerá primero.

Escribimos el bot

1. Crea el archivo polling.py.
2. Copia el código de abajo.
3. Ejecútalo con el comando python polling.py.
4. Escribe al bot cualquier mensaje en Telegram.

import time, requests
from config import PROXIES, BASE
offset = 0
print('Поллинг запущен через прокси')
while True:
try:
r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'timeout': 50}, proxies=PROXIES, timeout=60)
data = r.json()
except requests.RequestException as e:
print('Сетевая ошибка:', e)
time.sleep(3)
continue
if not data.get('ok'):
print('Ошибка API:', data)
time.sleep(3)
continue
for upd in data['result']:
offset = upd['update_id'] + 1
msg = upd.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Принял: ' + msg['text']}, proxies=PROXIES, timeout=15)

Analicemos qué ocurre aquí. El ciclo externo nunca termina por sí solo. El bloque try captura errores de red: corte del proxy, timeout, cambio de IP. Ante un error el script espera tres segundos y reintenta, en lugar de caerse. La verificación data.get('ok') atrapa errores de nivel API. El ciclo interno procesa cada actualización y avanza inmediatamente el offset.

Verificación: En la consola apareció la línea de inicio y tras enviar un mensaje el bot respondió «Принял: tu texto». Envía tres mensajes seguidos, el bot debe responder exactamente una vez a cada uno. Detén el script con Ctrl+C, envía un mensaje y vuelve a iniciar: el bot responderá al mensaje omitido, porque Telegram conserva las actualizaciones no procesadas hasta 24 horas.

Particularidades de los proxies móviles en polling

Los proxies móviles saben cambiar la dirección IP: por temporizador o por un enlace especial del panel. En el momento del cambio de IP la conexión abierta del polling se rompe. No es un error de tu código, es el comportamiento normal de la red. Nuestro ciclo ya está preparado: capturará la excepción, esperará y continuará desde el mismo offset. Ninguna actualización se perderá.

Sin embargo, una rotación frecuente genera ruido extra en los logs y microretrasos. Recomendación: para un bot con polling configura en el panel un intervalo de rotación de 10 minutos o más, o desactiva el cambio automático y cambia la IP por enlace solo cuando realmente lo necesites. Un bot no es un scraper, no necesita una dirección nueva cada minuto.

Consejo: Añade al log la hora y el update_id de cada actualización. Cuando dentro de una semana alguien diga que el bot no respondió, en un minuto encontrarás si el mensaje llegó a tu código o si el problema estuvo del lado de la red.

Posibles problemas

• Error 409 Conflict. El más frecuente. El bot tiene un webhook configurado, y el polling con webhook no pueden funcionar al mismo tiempo. Ejecuta curl -x tu_proxy https://api.telegram.org/botТОКЕН/deleteWebhook y reinicia el script. Segunda causa: hay dos copias del script en ejecución, cierra la sobrante.
• El bot responde dos veces a cada mensaje. El offset no avanza o hay dos copias del bot en ejecución.
• Read timed out constantes. El timeout del polling es mayor que el del proxy. Redúcelo a 30-40 segundos.
• Retraso de respuesta de 5-10 segundos. Verifica el tiempo de respuesta del proxy con curl. Si el canal en sí es lento, cambia el punto de salida o el plan.

Paso 4: Configuramos el webhook con HTTPS y token secreto

Objetivo de la etapa: Telegram envía por sí mismo las actualizaciones a tu servidor y el bot responde a través del proxy. Este paso requiere un VPS con dominio, así que si por ahora solo tienes polling y te funciona bien, puedes pasar al paso 5 y volver aquí después.

Preparación del servidor y el dominio

1. Alquila un VPS con Ubuntu. Anota su IP pública.
2. En el panel de gestión del dominio crea un registro A, por ejemplo bot.example.com, apuntando a la IP del servidor. Espera la actualización del DNS, normalmente 5-30 minutos. Verifícalo con el comando nslookup bot.example.com.
3. Conéctate al servidor por SSH y actualiza los paquetes: sudo apt update.
4. Instala nginx y certbot: sudo apt install nginx certbot python3-certbot-nginx.
5. Abre los puertos 80 y 443: sudo ufw allow 80, sudo ufw allow 443.
6. Obtén el certificado gratuito: sudo certbot --nginx -d bot.example.com. Sigue las indicaciones, introduce el email, acepta los términos. En un minuto el certificado estará emitido.

Telegram acepta webhooks solo por HTTPS con un certificado válido de una autoridad confiable. El certificado de certbot cumple ese requisito. Un certificado autofirmado también es posible, pero entonces habrá que subir su parte pública con el parámetro certificate en setWebhook, y eso añade complicaciones. Para principiantes, certbot es más simple.

Configuramos nginx como punto de entrada

Nginx recibirá las peticiones HTTPS de Telegram y las pasará a tu aplicación Flask, que escucha en el puerto local 8080. Abre el config del sitio creado por certbot con sudo nano /etc/nginx/sites-available/default y añade dentro del bloque server con puerto 443 este location:

location /tg/webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_read_timeout 30s;
}

Guarda el archivo, verifica la sintaxis sudo nginx -t y recarga sudo systemctl reload nginx.

Consejo: Haz que la ruta del webhook no sea obvia, por ejemplo /tg/webhook/k8s7d2f. No sustituye al token secreto, es una capa adicional: los escáneres aleatorios no encontrarán tu punto de entrada.

Escribimos el manejador del webhook

Crea en el servidor el archivo webhook.py. Recibe el POST de Telegram, verifica el encabezado secreto y responde al usuario a través del proxy. La función call la escribiremos en el siguiente paso; por ahora usa un requests.post normal con proxies.

import requests
from flask import Flask, request, abort
from config import PROXIES, BASE
app = Flask(__name__)
SECRET = 'MySecret123'
@app.post('/tg/webhook')
def webhook():
if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != SECRET:
abort(403)
update = request.get_json(silent=True) or {}
msg = update.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Получил через вебхук'}, proxies=PROXIES, timeout=15)
return 'ok', 200
if __name__ == '__main__':
app.run(host='127.0.0.1', port=8080)

Punto clave: el encabezado X-Telegram-Bot-Api-Secret-Token. Telegram lo añade a cada petición si indicaste secret_token al configurar el webhook. Cualquier petición sin el valor correcto se rechaza con código 403. Así nadie de fuera podrá inyectarle mensajes falsos al bot.

Inicia la aplicación: python webhook.py. Para el funcionamiento continuo más adelante lo configurarás como servicio systemd, pero para probar basta con el inicio directo.

Registramos el webhook a través del proxy

La propia llamada a setWebhook también pasa por el proxy, ya que es una petición saliente a Telegram Bot API. Ejecuta en cualquier máquina con acceso al proxy:

curl -x http://user:pass@proxy-host:8080 -F "url=https://bot.example.com/tg/webhook" -F "secret_token=MySecret123" -F "max_connections=40" -F "drop_pending_updates=true" https://api.telegram.org/bot123456789:AAExampleToken/setWebhook

Analicemos los parámetros. url — la dirección de tu manejador. secret_token — una cadena de 1 a 256 caracteres de letras latinas, dígitos, guion y guion bajo; debe coincidir con SECRET en el código. max_connections — cuántas peticiones simultáneas puede abrir Telegram hacia ti, de 1 a 100, por defecto 40. drop_pending_updates — reiniciar las actualizaciones acumuladas para que el bot no lance una avalancha de respuestas antiguas en el momento del cambio.

Respuesta esperada: {"ok":true,"result":true,"description":"Webhook was set"}.

Diagnóstico con getWebhookInfo

Esta es la herramienta principal para depurar webhooks. Ejecuta:

curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getWebhookInfo

En la respuesta fíjate en los campos: url debe coincidir con el tuyo, pending_update_count muestra la cola de actualizaciones sin procesar, last_error_date y last_error_message aparecen si Telegram no pudo entregar una actualización. Un campo de error vacío tras enviar un mensaje de prueba significa éxito total.

Verificación: Escribe al bot. Respondió «Получил через вебхук». En getWebhookInfo no hay last_error_message y pending_update_count es cero. En los logs de Flask se ve la línea POST /tg/webhook con código 200.

Atención: El manejador del webhook debe responder rápido, en pocos segundos. Si tu código tarda mucho, por ejemplo haciendo una consulta pesada a la base de datos o a un servicio externo a través de un proxy lento, Telegram considerará la entrega fallida y la repetirá. Mueve el trabajo pesado a una tarea en segundo plano y devuelve 200 al webhook de inmediato.

Posibles problemas

• last_error_message: SSL error. El certificado no es válido, expiró o fue emitido para otro dominio. Verifica sudo certbot certificates.
• Connection timed out. El puerto 443 está cerrado en el firewall o en el proveedor. Revisa sudo ufw status y la configuración del panel del VPS.
• Wrong response from the webhook: 403. El token secreto en el código y en setWebhook no coinciden. Revisa las mayúsculas.
• Wrong response from the webhook: 502. Flask no está corriendo o escucha en otro puerto. Verifica ss -tlnp | grep 8080.
• Bad webhook: port not allowed. Usa solo 443, 80, 88 u 8443.

Paso 5: Manejamos el error 429 y hacemos las peticiones resistentes

Objetivo de la etapa: escribir una sola función para todas las llamadas a Telegram Bot API que aguante la pausa ante un 429, reintente la petición ante fallos de red y proxy y nunca tumbe al bot.

Por qué no se puede ignorar el 429

Cuando envías una difusión a mil usuarios, el límite de 30 mensajes por segundo se alcanza al instante. Telegram responde 429 e indica retry_after. Si sigues machacando el servidor, los mensajes no saldrán, y el tiempo de espera en las siguientes respuestas aumentará. Al trabajar a través de proxy hay un matiz: los límites de Telegram están vinculados al bot, no a la IP. Cambiar la IP mediante rotación no ayudará a eludir la restricción y no debe usarse para eso. El único camino correcto es respetar retry_after y controlar la velocidad de envío.

Escribimos un envoltorio universal

Añade al archivo config.py o a un api.py aparte la siguiente función:

import time, requests
from config import PROXIES, BASE
def call(method, payload, retries=6):
for attempt in range(retries):
try:
r = requests.post(f'{BASE}/{method}', json=payload, proxies=PROXIES, timeout=15)
except requests.RequestException as e:
print('Сеть или прокси:', e)
time.sleep(min(2 ** attempt, 30))
continue
if r.status_code == 429:
wait = r.json().get('parameters', {}).get('retry_after', 1)
print('429 Too Many Requests, ждем', wait, 'сек')
time.sleep(wait + 0.5)
continue
if 500 <= r.status_code < 600:
print('Ошибка сервера Telegram', r.status_code)
time.sleep(min(2 ** attempt, 30))
continue
data = r.json()
if not data.get('ok'):
print('Ошибка API:', data.get('description'))
return data
raise RuntimeError('Telegram Bot API: исчерпаны попытки для ' + method)

Qué hace esta función. Ante un error de red espera exponencialmente: 1, 2, 4, 8 segundos, pero no más de 30. Así el bot sobrevive a un cambio de IP en el proxy o a un fallo breve del canal. Ante un 429 lee retry_after, añade medio segundo de margen y reintenta. Ante errores 5xx del lado de Telegram también reintenta con pausa. Ante errores 400 o 403, por ejemplo si el usuario bloqueó al bot, reintentar es inútil, así que la función devuelve la respuesta tal cual, y tú decides qué hacer después.

Limitamos la velocidad de antemano

Es mejor no llegar al 429 en absoluto. Para las difusiones añade una pausa entre mensajes. La variante más simple: time.sleep(0.05) después de cada envío da 20 mensajes por segundo, lo que está por debajo del límite general. Para un solo chat mantén una pausa no menor a un segundo. Para grupos, no más de 20 mensajes por minuto.

def broadcast(chat_ids, text):
sent, failed = 0, 0
for cid in chat_ids:
res = call('sendMessage', {'chat_id': cid, 'text': text})
if res.get('ok'):
sent += 1
else:
failed += 1
time.sleep(0.05)
print('Отправлено:', sent, 'Ошибок:', failed)

Consejo: Guarda las respuestas con error 403 Forbidden: bot was blocked by the user. Elimina a esos usuarios de la base de difusión. Esto reducirá la carga y protegerá de límites innecesarios, porque las peticiones fallidas también cuentan.

Probamos el manejo del 429

1. Crea un grupo de prueba y añade allí el bot.
2. Lanza un ciclo de 40 llamadas call('sendMessage', {...}) a ese chat sin pausas.
3. Observa en la consola: tras varios envíos rápidos aparecerá la línea sobre el 429 y el tiempo de espera.
4. Asegúrate de que tras la pausa el envío continuó y los 40 mensajes llegaron.

Verificación: Todos los mensajes fueron entregados, el bot no se cayó con una excepción, en el log se ven las pausas de retry_after. Reemplaza requests.post en polling.py y webhook.py por la función call, para que todo el trabajo con Telegram Bot API pase por un único canal protegido.

Posibles problemas

• retry_after enorme, cientos de segundos. Ignoraste el límite durante mucho tiempo. Detén el envío por completo, espera el tiempo indicado y reduce el ritmo.
• El 429 llega desde los primeros mensajes. Otro proceso usa el mismo token. Verifica que no esté corriendo una versión antigua del bot.
• La respuesta no es JSON en un 429. Algunos proxies devuelven su propia página HTML de error. Envuelve r.json() en try y si falla espera 5 segundos fijos.

Paso 6: Configuraciones avanzadas para proyectos con carga

Objetivo de la etapa: preparar el bot para crecer: varios bots a través de varios proxies, cola de envío, servidor Bot API local y rotación bien gestionada. Los principiantes pueden saltarse la sección y volver cuando los usuarios superen el millar.

Varios bots a través de distintos proxies

Los marketers suelen llevar una decena de bots para distintos proyectos en un mismo servidor. La arquitectura correcta: un diccionario proxies propio para cada bot y una sesión propia requests.Session(). La sesión reutiliza conexiones TCP, lo que reduce la carga del proxy y acelera las peticiones 2-3 veces. Guarda la configuración como una lista: token, dirección del proxy, modo de recepción de actualizaciones. Un proceso por bot es más fácil de depurar que un proceso para todos.

Cola de envío en lugar de llamadas directas

Para difusiones de más de 10 mil usuarios, las llamadas directas desde el código principal dejan de funcionar. Crea una cola: Redis o al menos una tabla en la base de datos con los campos chat_id, text, status, attempts. Un worker aparte toma las tareas y llama a la función call con control de velocidad. Ante un 429 el worker duerme, en lugar de bloquear la recepción de webhooks. Así el bot sigue respondiendo a los comandos de los usuarios mientras la difusión avanza en segundo plano. En 2026 Telegram Bot API permite a los bots de pago aumentar el límite hasta 1000 mensajes por segundo mediante el parámetro allow_paid_broadcast, pero eso consume Stars, así que para la mayoría de los proyectos una cola de 20-25 mensajes por segundo sigue siendo la opción óptima.

Servidor Bot API local

Telegram publica el código fuente del servidor Bot API, que puedes ejecutar en tu propia infraestructura. Tu código entonces se comunica no con api.telegram.org, sino con localhost, y el propio servidor local habla con Telegram. Ventajas: subida de archivos de hasta 2 GB en lugar de 50 MB, webhooks en cualquier puerto y sin HTTPS dentro de tu red, eliminación de varias restricciones. Desventaja: el proxy habrá que configurarlo a nivel del propio servidor local, no en el código del bot. Es una opción para equipos con competencias DevOps, para empezar es excesiva.

Rotación de IP y webhooks

Con webhooks, la rotación de IP en el proxy pasa casi inadvertida: cada llamada a sendMessage es breve, y un corte de conexión en el momento del cambio afectará como mucho a una petición, que el envoltorio call reintentará. Por eso, para webhooks es aceptable una rotación más frecuente que para el polling. Aun así, no tiene sentido cambiar con frecuencia: Telegram Bot API no limita las peticiones por IP, y los límites están vinculados al token. Configura la rotación por razones de tu infraestructura, no por la API.

Monitoreo de salud sin un sistema aparte

Conjunto mínimo que conviene implementar desde el principio: cada minuto llama a getWebhookInfo y escribe en el log pending_update_count y last_error_message. Si la cola crece en tres mediciones seguidas, tu manejador no da abasto. Para el polling registra la hora del último getUpdates exitoso: si pasaron más de dos minutos, la conexión se colgó, reinicia el proceso. Con eso basta para enterarte de los problemas antes que los clientes.

Consejo: Loguea no solo los errores, sino también el tiempo de cada petición a Telegram Bot API a través del proxy. Un crecimiento lento del tiempo medio de respuesta de 0,3 a 2 segundos te avisará de la degradación del canal días antes de que el bot empiece a perder mensajes.

Verificación del resultado: checklist de la solución lista

Repasa la lista. Cada punto debe estar marcado, solo entonces el bot se considera listo para trabajar con usuarios reales.

Checklist

• El comando curl con el parámetro -x a través del proxy devuelve "ok":true en el método getMe.
• El script check.py muestra la IP del proxy, no la tuya.
• El polling responde al mensaje una sola vez, sin duplicados.
• Tras detener y reiniciar el polling, los mensajes omitidos se procesan.
• Ante un cambio forzado de IP en el proxy, el polling se recupera solo en 3-5 segundos.
• Webhook: getWebhookInfo muestra tu url, pending_update_count en cero y last_error_message vacío.
• Una petición al webhook sin el encabezado secreto recibe 403.
• El envío rápido de 40 mensajes a un mismo chat pasa sin caídas, en el log se ven las pausas de retry_after.
• El token y los datos del proxy están en .env, no en el código.

Cómo probar el conjunto completo

1. Inicia el bot en el modo elegido.
2. Escríbele desde tres cuentas distintas con dos mensajes cada una.
3. Confirma seis respuestas, una por cada mensaje.
4. Pulsa en el panel del proxy el enlace de cambio de IP y envía otro mensaje de inmediato.
5. El bot debe responder en menos de 10 segundos.
6. Lanza el test de 429 del paso 5.
7. Revisa los logs: sin excepciones sin manejar ni trazas de error.

Indicadores de éxito

Tiempo de respuesta del bot a un mensaje por debajo de 2 segundos. Porcentaje de peticiones fallidas a Telegram Bot API tras todos los reintentos por debajo del 0,1 por ciento. Ni un solo duplicado en 24 horas de trabajo. pending_update_count en getWebhookInfo no supera los diez en horas pico. Si los indicadores coinciden, felicidades: armaste un esquema confiable que te servirá durante muchos meses.

Errores típicos y sus soluciones

Error 409 Conflict en getUpdates

Causa: el bot tiene un webhook configurado o hay dos instancias de polling en ejecución. Solución: llamar a deleteWebhook a través del proxy, asegurarte de que solo corre un proceso. Verifica con el comando ps aux | grep polling.

El bot responde dos veces a cada mensaje

Causa: el offset no aumenta o hay dos copias del bot en distintos servidores con el mismo token. Solución: revisa la línea offset = update_id + 1, detén las copias sobrantes. Para el webhook asegúrate de que nginx no duplique las peticiones a dos backends.

Error 407 Proxy Authentication Required

Causa: credenciales del proxy incorrectas o caracteres especiales sin codificar en la contraseña. Solución: verifica el usuario y la contraseña en el panel, codifica @, : y / en la contraseña, prueba la autenticación por IP si está disponible en tu plan.

Read timed out cada 50-60 segundos

Causa: el timeout del polling es mayor o igual al timeout de inactividad del proxy. Solución: baja el timeout de getUpdates a 30-40 segundos y mantén el timeout del cliente 10 segundos por encima.

El webhook está configurado, pero no llegan actualizaciones

Causa: el puerto está cerrado, el certificado no es válido o el manejador no responde 200. Solución: mira last_error_message en getWebhookInfo, es el diagnóstico exacto. Comprueba curl -I https://bot.example.com/tg/webhook desde otra computadora.

Wrong response from the webhook: 403 Forbidden

Causa: el token secreto en el código es distinto del enviado en setWebhook. Solución: reinstala el webhook con el mismo valor que está en el código. Recuerda que setWebhook con nuevos parámetros reemplaza por completo los anteriores.

429 constantes con poca carga

Causa: el bot envía a un mismo chat más de una vez por segundo, por ejemplo varios mensajes seguidos en respuesta a un comando. Solución: combina las respuestas en un solo mensaje, usa editMessageText en lugar de mensajes nuevos para el progreso, añade una pausa entre envíos a un mismo chat_id.

El tráfico va directo, sin pasar por el proxy

Causa: el diccionario proxies no tiene la clave https, la variable de entorno no es visible para el proceso, el framework no tomó la configuración. Solución: verifica la IP de salida con una petición a api.ipify.org dentro del mismo código con el que envías mensajes. No confíes en suposiciones, comprueba de hecho.

SSL: CERTIFICATE_VERIFY_FAILED en peticiones a través del proxy

Causa: conjunto de certificados raíz desactualizado o hora del sistema incorrecta. Solución: actualiza certifi, sincroniza la hora. Nunca desactives la verificación de certificados con el parámetro verify=False: eso abre la posibilidad de sustitución de tráfico con el token.

FAQ: preguntas frecuentes sobre la configuración

¿Qué elegir para empezar: polling o webhook?

Polling. Funciona desde cualquier lugar, no requiere dominio ni certificado, y puedes cambiar a webhook más tarde en una hora. El webhook tiene sentido cuando el bot atiende a miles de usuarios o funciona en un servidor donde ya hay HTTPS.

¿Puedo usar un mismo proxy para varios bots?

Sí. Los límites de Telegram Bot API están vinculados al token del bot, no a la IP. Diez bots a través de un mismo proxy no se estorban entre sí desde el punto de vista de la API. La única limitación es el ancho de banda del propio proxy, para bots de texto es más que suficiente.

¿Es obligatorio pasar por proxy tanto el webhook como las respuestas?

Las peticiones entrantes del webhook llegan directamente a tu servidor, es imposible pasarlas por proxy por definición. Solo van por proxy las llamadas salientes: sendMessage, setWebhook, getFile y los demás métodos. Es el esquema normal y el único posible.

¿Cómo saber que las peticiones realmente van por el proxy?

Dentro del mismo código solicita https://api.ipify.org con las mismas opciones proxies y compárala con tu IP real. Además puedes mirar las estadísticas de tráfico en el panel del proxy: el contador debe crecer mientras el bot trabaja.

¿Qué hacer si cambia la IP del proxy durante el trabajo del bot?

Nada, si usaste el código de esta guía. El polling capturará la ruptura de conexión y continuará desde el offset guardado. La función call reintentará la petición fallida. La única recomendación: no configures rotación más seguida que cada varios minutos en modo polling.

¿SOCKS5 o proxy HTTP para Telegram Bot API?

Para el bot casi no hay diferencia, ambos funcionan. El proxy HTTP es más simple de configurar y es compatible con todos los clientes sin paquetes adicionales. SOCKS5 es más cómodo cuando quieres garantizar la resolución de DNS del lado del proxy mediante el esquema socks5h. Elige el que ya uses en otros proyectos.

¿Cuántos mensajes puedo enviar sin recibir 429?

Mantente en las referencias: hasta 1 mensaje por segundo a un chat personal, hasta 20 por minuto a un grupo, hasta 25-30 por segundo en total. Para difusiones masivas calcula 20 mensajes por segundo y maneja obligatoriamente retry_after, porque los límites pueden bajar temporalmente cuando Telegram está bajo alta carga.

¿Cómo migrar de forma segura un bot que ya funciona a proxy?

Primero verifica el proxy con curl en getMe. Luego añade la variable HTTPS_PROXY o configura proxies en el código, lanza el bot con un token de prueba. Solo tras verificaciones exitosas cambia al token de producción. Ten la configuración antigua a mano para el rollback.

¿Cómo revertir el webhook y volver al polling?

Una sola llamada a deleteWebhook a través del proxy. Si quieres conservar las actualizaciones acumuladas para el polling, no envíes drop_pending_updates. Después de eso lanza polling.py y el bot retomará la cola.

¿Se pueden configurar varias URL de webhook para un mismo bot?

No, un bot tiene exactamente un webhook. Si necesitas distribuir la carga, coloca detrás de la única URL un balanceador nginx que reparta las peticiones entre varias instancias de la aplicación. Para Telegram eso se ve como un único punto de entrada.

Conclusión

Resumamos el trabajo realizado. Creaste un bot y obtuviste el token, aprendiste a verificar el proxy con curl y Python, confirmaste que el tráfico a Telegram Bot API va por la ruta correcta. Armaste un ciclo resistente de long polling que sobrevive al cambio de IP y no duplica mensajes. Levantaste un webhook con un certificado HTTPS real y lo protegiste con un token secreto. Y lo más valioso: escribiste una función que respeta retry_after ante un 429, reintenta las peticiones ante fallos de red y convierte un canal caprichoso en uno confiable.

Qué hacer después. Configura el bot como servicio systemd para que se levante tras un reinicio del servidor. Mueve los tokens y las direcciones de proxy a variables de entorno en la máquina de producción. Añade un registro simple de tiempos de respuesta y revísalo una vez por semana. Si los usuarios se multiplican, pasa a la cola de envío de la sección avanzada.

Hacia dónde crecer. Estudia los métodos de Telegram Bot API para botones inline, pagos y miniapps, abren a los bots escenarios completamente nuevos para marketing y ventas. Domina los frameworks asíncronos aiogram o python-telegram-bot, ellos se encargarán de la rutina del polling y los reintentos, y tú ya entiendes qué ocurre bajo el capó. Y lo principal: no tengas miedo de experimentar con el bot de prueba. Cada error 429 o 409 que atrapaste y arreglaste por tu cuenta te hace más fuerte que cualquier plantilla lista. Todo te va a salir bien.