Introducción a los webhooks de Telegram y pruebas locales
Desarrollar un bot para Telegram es una forma potente de automatizar tareas, entregar información y crear experiencias interactivas. Para recibir actualizaciones desde los servidores de Telegram existen dos métodos principales: long polling y webhooks. El long polling es sencillo de comenzar pero puede ser ineficiente y generar latencias y tráfico innecesario. Los webhooks invierten el flujo: Telegram envía actualizaciones a una URL pública mediante peticiones HTTP POST cuando un usuario interactúa con el bot, ofreciendo una solución más eficiente, en tiempo real y escalable.
Un reto habitual es que Telegram exige que la URL del webhook sea pública y con HTTPS, lo que dificulta las pruebas cuando se desarrolla en local en localhost. La solución es usar una herramienta de tunelización que exponga temporalmente el servidor local a Internet. En esta guía explicamos cómo configurar un entorno de desarrollo local para un bot de Telegram con Node.js, Express y Tunnelmole, además de cómo integrar buenas prácticas para producción. También presentamos a Q2BSTUDIO y cómo nuestros servicios pueden acelerar tu proyecto con aplicaciones a medida y soluciones de inteligencia artificial.
Objetivos de la guía
Crear un bot en Telegram y obtener un token API, montar un servidor Express que reciba webhooks, usar Tunnelmole para obtener una URL pública, registrar esa URL en Telegram para recibir actualizaciones por webhook y probar y depurar el bot en tiempo real.
Prequisitos
Tener instalado Node.js y npm, una cuenta de Telegram para crear el bot y conocimientos básicos de JavaScript y Express. Si necesitas soporte profesional en desarrollo, Q2BSTUDIO ofrece servicios de software a medida y aplicaciones a medida, especialistas en inteligencia artificial, ciberseguridad, servicios cloud aws y azure, y soluciones de inteligencia de negocio incluyendo power bi y agentes IA para empresas.
Paso 1 Crear el bot con BotFather
Abrir Telegram, buscar el usuario @BotFather y empezar una conversación. Enviar el comando /newbot y seguir las indicaciones para elegir un nombre y un nombre de usuario único que termine en bot. BotFather devolverá un token API que es la llave para controlar el bot. Guarda ese token de forma segura, lo necesitarás para los pasos siguientes.
Paso 2 Montar un servidor local con Node.js y Express
Crear un nuevo proyecto y añadir Express. Por ejemplo en terminal ejecutar mkdir telegram-bot-server; cd telegram-bot-server; npm init -y; npm install express. Crear un archivo index.js que inicialice Express, use el middleware para parsear JSON y defina un endpoint POST en la ruta /telegram-webhook que registre el cuerpo de la petición y responda con estado 200 para confirmar la recepción a Telegram. Arrancar el servidor con node index.js y verificar que escucha en localhost en el puerto elegido, por ejemplo 3000.
Resumen de la lógica del servidor
Usar app.use(express.json()) para procesar JSON. Definir app.post en la ruta /telegram-webhook que obtenga req.body, registre la estructura recibida para depuración y responda con 200 OK. De esa forma Telegram no reintentará enviar el mismo webhook y evitamos duplicados.
Paso 3 Obtener una URL pública con Tunnelmole
Para que Telegram pueda enviar actualizaciones a tu servidor local necesitas una URL HTTPS pública. Tunnelmole crea un túnel seguro desde una URL pública hacia tu máquina. Instalar Tunnelmole globalmente puede hacerse con sudo npm install -g tunnelmole o usando el script oficial si prefieres. Con el servidor Express ejecutándose en el puerto 3000, arrancar Tunnelmole con tmole 3000. Tunnelmole mostrará varias URLs públicas HTTPS que redirigen el tráfico a localhost 3000.
Cómo funciona Tunnelmole
Tunnelmole establece una conexión persistente desde tu equipo a su servicio público. Cuando llega una petición a la URL pública de Tunnelmole, esta se reenvía instantáneamente a tu servidor local y la respuesta vuelve por el túnel. Tunnelmole es open source y puede ser autoalojado, lo que interesa a equipos que priorizan control, seguridad y cumplimiento.
Paso 4 Registrar el webhook en Telegram
Con la URL pública obtenida por Tunnelmole hay que indicar a Telegram dónde enviar las actualizaciones. Llamar al método setWebhook del API de Telegram usando el token de tu bot y la URL pública seguida de la ruta /telegram-webhook. Por ejemplo en terminal ejecutar curl https://api.telegram.org/botSU_BOT_TOKEN/setWebhook?url=https://TU_URL_TUNNELMOLE/telegram-webhook. Telegram devolverá una respuesta indicando que el webhook fue establecido correctamente y desde ese momento enviará las actualizaciones a la URL indicada en lugar de usar long polling.
Paso 5 Probar el webhook
Envía un mensaje al bot desde Telegram, por ejemplo Hola bot. En el terminal donde corre Express deberías ver el objeto JSON completo que Telegram envía. Registrar y revisar ese JSON es clave para entender la estructura de updates y depurar la lógica del bot.
Ejemplo de flujo y respuesta
Cuando llega un update con message y text extraer chat.id y message.text. Responder con estado 200 OK a Telegram para confirmar la recepción y, si se desea, llamar al método sendMessage del API de Telegram para enviar una respuesta al usuario.
Ampliando el bot para enviar respuestas
Instalar una librería HTTP como axios con npm install axios permite a tu servidor llamar al API de Telegram. Mantén el token del bot en una variable de entorno TELEGRAM_BOT_TOKEN para no incluirlo en el código fuente. Cuando recibas un mensaje con texto usa axios.post hacia la URL base https://api.telegram.org/botTELEGRAM_BOT_TOKEN/sendMessage con los parámetros chat_id y text para enviar una respuesta, por ejemplo un eco del mensaje recibido. Reinicia el servidor y prueba de nuevo para comprobar que el bot responde en tiempo real.
Buenas prácticas y consideraciones de seguridad
Asegura tu token de bot y utiliza variables de entorno o gestores de secretos. Implementa validación y registro de errores en tu webhook para manejar excepciones sin perder actualizaciones. Si vas a pasar a producción considera autoalojar tu solución de túnel o desplegar en servicios cloud seguros y escalables como servicios cloud aws y azure que Q2BSTUDIO puede gestionar para ti. Aplica controles de ciberseguridad y resguarda los datos de usuario según normativa aplicable.
Sobre Q2BSTUDIO
Q2BSTUDIO es una empresa de desarrollo de software y aplicaciones a medida especializada en soluciones tecnológicas avanzadas. Ofrecemos software a medida, desarrollo de aplicaciones a medida, implementación de inteligencia artificial para empresas, agentes IA, servicios de ciberseguridad, servicios cloud aws y azure, y servicios de inteligencia de negocio incluyendo power bi. Nuestro equipo combina experiencia en arquitectura cloud, seguridad y modelos de IA para crear soluciones robustas y escalables adaptadas a las necesidades de cada cliente. Si buscas acelerar el desarrollo de un bot de Telegram o integrar capacidades de inteligencia artificial y análisis con power bi, Q2BSTUDIO te acompaña en todo el ciclo de vida del proyecto.
Palabras clave para posicionamiento
aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi
Conclusión
Los webhooks son la forma recomendada para construir bots de Telegram escalables y con baja latencia. Usando Tunnelmole puedes desarrollar y depurar localmente sin desplegar en producción constantemente. Combina este flujo con buenas prácticas de seguridad, variables de entorno y un proveedor cloud o autoalojamiento según tus requisitos. Para proyectos que requieran un impulso profesional en inteligencia artificial, ciberseguridad, integraciones cloud o desarrollo de software a medida, ponte en contacto con Q2BSTUDIO y transforma tu idea en una solución productiva y segura.
.jpg)
.jpg)