Configuración de webhook de bot de Telegram: guía completa para desarrolladores

La configuración de webhook de bot de Telegram conecta tu servidor al flujo de actualizaciones de Telegram para que los mensajes lleguen en tiempo real en lugar de en un bucle de sondeo. Si estás construyendo un bot personalizado con la Bot API, los webhooks son la ruta de producción estándar: Telegram POSTea cada actualización a tu endpoint HTTPS, y tu código responde.

Esta guía te lleva a través de los requisitos previos, el registro, un ejemplo de manejador funcional, la verificación, la resolución de problemas y cuándo una plataforma gestionada como TeleClaw tiene más sentido que el autoalojamiento.

Puntos clave

• Los webhooks y el long polling son mutuamente excluyentes. Configurar un webhook deshabilita getUpdates hasta que lo elimines.
• HTTPS es obligatorio. Tu endpoint necesita TLS 1.2+, un certificado coincidente y el puerto 443, 80, 88 o 8443.
• Regístrate con setWebhook, verifica con getWebhookInfo. Revisa last_error_message cuando las actualizaciones dejen de fluir.
• Usa secret_token para confirmar que las solicitudes provienen de Telegram, no de escáneres aleatorios que acceden a tu URL.
• Alternativa sin código: TeleClaw maneja el alojamiento y la entrega para que te saltes completamente la capa del servidor.

Webhooks vs long polling: cuál elegir

Telegram ofrece dos formas de recibir actualizaciones. Según las Preguntas Frecuentes de Bots, eliges un método por bot. No puedes ejecutar ambos al mismo tiempo.

El long polling es la forma más rápida de prototipar. Tu bot llama a getUpdates en un bucle, procesa cada lote y avanza el offset. Sin dominio, sin certificado, sin puerto abierto.

Los webhooks invierten el modelo. Telegram envía un POST HTTPS a tu URL cada vez que alguien envía un mensaje al bot. Eso elimina las solicitudes de sondeo inactivas y reduce el tiempo de reacción, lo cual es importante para bots de soporte, flujos de pago y moderación de grupos a escala.

Si aún estás registrando el bot, comienza con nuestra guía para crear un bot de Telegram para obtener un token de BotFather antes de continuar aquí.

Requisitos previos para la configuración de webhook de bot de Telegram

Antes de llamar a setWebhook, confirma que tu infraestructura cumple con los requisitos de Telegram de la guía oficial de webhooks:

• Token de bot de @BotFather (consulta la guía de creación de bots enlazada anteriormente).
• Dominio público con un certificado TLS válido. Los certificados autofirmados funcionan solo si subes la clave pública a través del parámetro certificate.
• Puerto soportado en tu servidor: 443 (predeterminado), 80, 88 o 8443. Otros puertos son rechazados.
• CN o SAN del certificado debe coincidir con el dominio en tu URL de webhook. Los certificados comodín pueden no funcionar. Las redirecciones no son compatibles.
• Acceso POST entrante desde las subredes de Telegram 149.154.160.0/20 y 91.108.4.0/22.

Para el desarrollo local, expón localhost a través de un túnel (ngrok, Cloudflare Tunnel o similar) que te dé una URL HTTPS pública. Prueba que el túnel devuelve HTTP 200 para las solicitudes POST antes de registrar el webhook.

Paso 1: Construye tu endpoint de webhook

Tu servidor necesita una ruta que acepte solicitudes POST, analice el objeto JSON Update y devuelva HTTP 200 rápidamente. Los manejadores lentos hacen que Telegram reintente y eventualmente reporte errores en getWebhookInfo.

Ejemplo mínimo de Node.js con Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python con Flask sigue el mismo patrón: lee JSON de request, valida el encabezado secreto si está configurado, procesa la actualización, devuelve 200.

Responde rápido. El trabajo pesado (escrituras en la base de datos, llamadas a la API de IA) debe ir a una cola en segundo plano. Telegram espera un reconocimiento rápido. También puedes responder en línea devolviendo un cuerpo JSON con un campo method en lugar de hacer una llamada a la API separada, como se describe en las notas de webhook de la Bot API.

Paso 2: Configurar el webhook del bot de Telegram con setWebhook

Una vez que tu endpoint esté activo, regístralo con la Bot API. Reemplaza <TOKEN> y la URL con tus valores.

Usando curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Referencia de parámetros:

• url (obligatorio): Tu endpoint HTTPS. Usa una cadena vacía para eliminar el webhook.
• secret_token (opcional): 1-256 caracteres (A-Z, a-z, 0-9, _, -). Telegram lo envía en el encabezado X-Telegram-Bot-Api-Secret-Token.
• max_connections (opcional): 1-100 conexiones simultáneas. El valor predeterminado es 40.
• allowed_updates (opcional): Limita los tipos de actualización que recibes. Reduce el tamaño de la carga útil si solo manejas mensajes.
• drop_pending_updates (opcional): Establece true para descartar las actualizaciones pendientes al cambiar de webhooks.
• certificate (opcional): Sube tu archivo de clave pública para certificados autofirmados.

Una respuesta exitosa se ve así: {"ok":true,"result":true,"description":"Webhook was set"}.

Paso 3: Verificar con getWebhookInfo

Siempre confirma el registro inmediatamente. Esta es tu primera herramienta de resolución de problemas cuando las actualizaciones dejan de llegar.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Ejemplo de respuesta:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Observa estos campos:

• url: Vacío significa que no hay webhook activo (el bot está en long polling).
• pending_update_count: Actualizaciones en cola esperando ser entregadas. Un número creciente indica fallos en la entrega.
• last_error_date y last_error_message: La razón del fallo más reciente. Soluciona la causa raíz, luego Telegram reintenta automáticamente.
• ip_address: Qué IP de Telegram está accediendo actualmente a tu endpoint.

Envía un mensaje de prueba a tu bot desde una cuenta real de Telegram. Si pending_update_count se mantiene en cero y los registros de tu servidor muestran el POST, la configuración del webhook del bot de Telegram está funcionando.

Ejemplo de webhook de bot de Telegram: manejador de solicitud de unión

Los bots de solicitud de unión (flujos de admisión estilo Guardian) necesitan el tipo de actualización chat_join_request. Nuestra guía de bot Guardian cubre el lado del producto. Aquí está el cableado del webhook.

Regístrate con las solicitudes de unión habilitadas:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Lógica del manejador (pseudocódigo):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Ejecuta la lógica de filtrado, luego aprueba o rechaza a través de la Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram entrega las solicitudes de unión como actualizaciones push, por lo que los webhooks son una opción natural para los bots de admisión que deben responder antes de que expire la solicitud.

Eliminar el webhook del bot de Telegram y volver al sondeo

¿Necesitas depurar localmente con getUpdates? Primero elimina el webhook.

Opción A con deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Opción B con setWebhook y URL vacía:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Ambos métodos vuelven a habilitar el long polling. Si omites este paso, getUpdates no devuelve nada porque el webhook todavía está registrado en tu URL de producción.

Solución de problemas comunes de webhook

Cuando getWebhookInfo muestra errores, relaciona el mensaje con una solución:

Ejecuta getWebhookInfo en un horario en producción. Detectar last_error_message a tiempo evita horas de pérdida silenciosa de mensajes.

Omite el servidor: bots gestionados con TeleClaw

No todos los bots necesitan una infraestructura de webhook personalizada. Si tu objetivo es un asistente de IA para un grupo o canal de negocios, el alojamiento y la entrega de actualizaciones son problemas resueltos.

TeleClaw conecta tu token de BotFather a un tiempo de ejecución gestionado impulsado por OpenClaw. Configuras la personalidad, la base de conocimientos y las reglas de moderación en el panel de control. La plataforma maneja los endpoints HTTPS, el escalado y el enrutamiento del modelo de IA. Añade @claw como administrador de grupo y entra en funcionamiento sin escribir un manejador de webhook.

Explora lo que un bot gestionado puede hacer en la página de características de TeleClaw. Para un recorrido completo sin código, consulta nuestra guía de chatbot de Telegram sin código.

Los webhooks personalizados aún tienen sentido cuando necesitas control total: backends propietarios, residencia de datos regulada o procesamiento de actualizaciones no estándar. Para todo lo demás, el costo operativo de la gestión de certificados, la monitorización y el manejo de reintentos se acumula rápidamente.

Conclusión

La configuración de webhook de bot de Telegram se reduce a cuatro pasos: desplegar un endpoint HTTPS, llamar a setWebhook, verificar con getWebhookInfo y monitorear los errores. Usa secret_token para la validación de solicitudes, limita allowed_updates a lo que procesas y mantén los manejadores rápidos.

Los desarrolladores que desean una entrega push de producción sin ejecutar servidores pueden usar TeleClaw en su lugar. Pega tu token, configura el comportamiento de la IA y concéntrate en lo que dice el bot en lugar de cómo llegan las actualizaciones.

¿Listo para lanzar un bot de IA sin gestionar webhooks? Añade @claw a tu grupo de Telegram →