Bot de Telegram con Node-RED para dispositivos MQTT: alertas, consultas de estado y comandos remotos

Combinar Node-RED y Telegram te ofrece una forma gratuita e inmediata de recibir alertas de dispositivos MQTT y de enviarles comandos desde el móvil. En este tutorial crearás un bot de Telegram, lo conectarás a Node-RED, reenviarás alertas de umbral desde un topic MQTT, responderás al comando /status con la última lectura y conmutarás un relé con /on y /off, ignorando a cualquiera que no esté en tu lista de autorizados.

Por qué Telegram funciona bien para las notificaciones IoT

El correo electrónico está bien para informes, pero se tarda en verlo y es fácil que acabe filtrado. Los bots de Telegram se crean gratis, las notificaciones push llegan al teléfono rápidamente y la Bot API es bidireccional: el mismo chat que recibe una alerta puede responder con un comando. Para un laboratorio doméstico, un invernadero, un pequeño taller o un equipo de mantenimiento de guardia, a menudo es justo la cantidad de herramientas que hace falta.

Node-RED es un buen anfitrión para el bot porque ya habla MQTT de forma nativa. El bot nunca habla directamente con tus dispositivos. Habla con Node-RED, y Node-RED publica y se suscribe en el broker, lo que mantiene tus dispositivos sencillos y completamente ajenos a Telegram.

Qué necesitas

1. Una instancia de Node-RED en funcionamiento (local, Raspberry Pi o Docker).
2. Una cuenta de Telegram.
3. Un broker MQTT. Esta guía usa ConnectMQ; para las pruebas utilizamos el servidor MQTT público gratuito en broker.connectmq.com con el prefijo connectmq/demo/tg42x9. Sustituye tg42x9 por tu propia cadena aleatoria.
4. El paquete node-red-contrib-telegrambot.

Como cualquier cosa bajo el área pública de demostración puede ser leída por otros usuarios, no publiques allí comandos reales para equipos reales. Pasa a credenciales privadas antes de conectar nada importante.

Paso 1: crea el bot con BotFather

En Telegram, abre un chat con @BotFather y envía /newbot. Elige un nombre visible y un nombre de usuario que termine en bot. BotFather responde con un token de API con el aspecto 123456789:AA.... Trátalo como una contraseña: cualquiera que tenga el token puede controlar el bot.

Opcionalmente, envía /setcommands a BotFather y registra la lista de comandos para que Telegram muestre sugerencias:

status - Show the latest sensor values
on - Switch the relay on
off - Switch the relay off

Paso 2: instala y configura los nodos de Telegram

Instala node-red-contrib-telegrambot desde Menu → Manage palette. Añade tres nodos que vamos a usar:

Crea un nodo de configuración del bot, pega el token y usa el modo polling por defecto. El polling funciona detrás de NAT y de routers domésticos porque Node-RED solicita las actualizaciones a Telegram en lugar de esperar conexiones entrantes. El nodo de configuración también permite restringir el bot a nombres de usuario o chat IDs concretos. Úsalo, y añade tu propia comprobación en el flujo como segunda capa.

Encuentra tu chat ID

Conecta un nodo Telegram receiver a un nodo debug configurado para mostrar el mensaje completo, despliega y envía cualquier texto a tu bot. La barra lateral de depuración muestra msg.payload.chatId. Anótalo; lo usarás para la lista de autorizados y para enviar alertas no solicitadas.

Paso 3: reenvía alertas MQTT a Telegram

El nodo sender espera que msg.payload sea un objeto con un chat ID, un tipo y el contenido. Suscríbete a un topic de alertas con un nodo mqtt in (connectmq/demo/tg42x9/alerts/#) y convierte cada mensaje con un nodo function:

const CHAT_ID = 123456789;   // your chat ID from the debug sidebar

let text = msg.payload;
if (typeof text === "object") text = JSON.stringify(text);

// Topic like connectmq/demo/tg42x9/alerts/freezer -> "freezer"
const source = msg.topic.split("/").pop();

msg.payload = {
    chatId: CHAT_ID,
    type: "message",
    content: `Alert from ${source}: ${text}`
};
return msg;

Conéctalo a un nodo Telegram sender. Si tus alertas provienen de valores de sensor en bruto en lugar de un topic de alertas dedicado, coloca delante de esta función la lógica de histéresis y de tiempo de espera de nuestro tutorial de alertas por email con Node-RED para que el bot no te escriba con cada lectura.

Paso 4: responde a /status con los últimos valores

Guarda el último valor de cada sensor en el contexto del flujo. Suscríbete a connectmq/demo/tg42x9/sensors/# y almacena cada lectura:

const name = msg.topic.split("/").pop();
const latest = flow.get("latest") || {};
latest[name] = { value: msg.payload, at: new Date().toISOString() };
flow.set("latest", latest);
return null;

Después añade un nodo Telegram command con el comando /status, seguido de esta función y de un Telegram sender:

const ALLOWED = [123456789];   // allowed chat IDs

const chatId = msg.payload.chatId;
if (!ALLOWED.includes(chatId)) {
    node.warn("Ignored /status from chat " + chatId);
    return null;
}

const latest = flow.get("latest") || {};
const names = Object.keys(latest);

let text;
if (names.length === 0) {
    text = "No sensor data received yet.";
} else {
    text = names
        .map(n => `${n}: ${JSON.stringify(latest[n].value)} (at ${latest[n].at.substring(11, 19)} UTC)`)
        .join("\n");
}

msg.payload = { chatId, type: "message", content: text };
return msg;

Incluir la hora de la última lectura es importante. Un valor que parece normal pero tiene dos horas de antigüedad suele indicar que el dispositivo está desconectado.

Paso 5: envía comandos a dispositivos MQTT

Añade nodos Telegram command para /on y /off. Ambos alimentan un único nodo function que comprueba el remitente y construye dos mensajes: un comando para el dispositivo y una confirmación para el chat.

const ALLOWED = [123456789];
const chatId = msg.payload.chatId;
if (!ALLOWED.includes(chatId)) return [null, null];

// The command node's configured command tells us which one fired
const text = (msg.payload.content || "").toString().toLowerCase();
const state = text.includes("off") ? "OFF" : "ON";

const mqttMsg = {
    topic: "connectmq/demo/tg42x9/relay1/set",
    payload: JSON.stringify({ state, by: "telegram", chatId }),
    qos: 1,
    retain: false
};

const reply = {
    payload: { chatId, type: "message", content: `Relay 1 command sent: ${state}` }
};

return [mqttMsg, reply];

Configura la función con dos salidas, conecta la primera a un nodo mqtt out y la segunda a un Telegram sender. Si en tu versión del nodo el campo content no contiene el texto del comando, usa dos nodos function separados, uno por comando, con el estado fijado en el código. Es menos ingenioso y más robusto.

Una respuesta mejor espera a que el dispositivo confirme. Haz que el dispositivo publique su estado real en connectmq/demo/tg42x9/relay1/state y reenvía ese topic a Telegram con la función de alertas del paso 3. Así sabrás que el relé conmutó, no solo que un comando salió de Node-RED. Nuestra guía de Node-RED de HTTP a MQTT usa el mismo patrón de comando y confirmación para clientes HTTP.

Prueba el circuito completo

# Watch the command topic
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-tg42x9 -v -t "connectmq/demo/tg42x9/#"

# Simulate a sensor and an alert
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-tg42x9 -t "connectmq/demo/tg42x9/sensors/freezer" -m "-17.5"
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-tg42x9 -t "connectmq/demo/tg42x9/alerts/freezer" -m "Door open for 5 minutes"

Después envía /status, /on y /off al bot y observa cómo aparecen los mensajes de comando en la terminal del suscriptor.

Lista de seguridad para un bot de Telegram con Node-RED

Un bot que puede conmutar equipos es un mando a distancia, así que trátalo como tal:

1. Lista de autorizados de chat IDs en el nodo de configuración del bot y de nuevo en cada función que ejecute un comando.
2. Mantén el token en secreto. Debe estar en las credenciales del nodo de configuración, no en el JSON del flujo que exportas o subes a un repositorio.
3. Usa credenciales privadas de ConnectMQ y TLS (puerto 8883) para todo lo que vaya más allá de una demo. En el servidor público, cualquiera puede leer y publicar bajo cualquier topic de demostración.
4. Haz que los comandos sean idempotentes. Enviar /on dos veces debe dejar el relé encendido, no conmutarlo.
5. Registra cada comando con el chat ID y la hora, por ejemplo en una base de datos o en un topic de auditoría retenido.
6. Protege el editor. Activa adminAuth en settings.js para que nadie pueda modificar el flujo ni la lista de autorizados.

Solución de problemas

Ejecuta tu bot de Telegram con Node-RED en ConnectMQ

Cuando el bot funcione en el broker de demostración, cambia la configuración de broker de Node-RED a un broker privado de ConnectMQ, un broker MQTT gestionado: puerto 8883 con TLS y el usuario, la contraseña y el client ID generados en el portal. El cliente MQTT integrado en el navegador y el explorador de topics en vivo del portal resultan muy útiles para observar los topics de comando y de estado mientras pruebas desde el móvil. Regístrate en el plan gratuito Serverless en app.connectmq.com sin tarjeta de crédito. Si todavía estás decidiendo dónde debe estar tu broker, nuestra visión general del broker MQTT en la nube explica las opciones, y el tutorial de Node-RED y MQTT cubre el resto de los fundamentos de Node-RED.

Preguntas frecuentes

¿Qué paquete de Node-RED debo usar para Telegram?

node-red-contrib-telegrambot es la opción más utilizada. Proporciona nodos receiver, command y sender, admite los modos polling y webhook y puede restringir el acceso a usuarios o chats conocidos.

¿Necesito una IP pública o redirección de puertos?

No. En modo polling, Node-RED hace peticiones salientes a Telegram, y MQTT también es una conexión saliente hacia el broker, así que ambos funcionan detrás de un router doméstico.

¿Pueden varias personas usar el mismo bot?

Sí. Añade el chat ID de cada persona a la lista de autorizados, o añade el bot a un grupo y usa el chat ID del grupo para las alertas.

¿Es seguro controlar dispositivos desde Telegram?

Puede serlo si restringes los chat IDs, mantienes el token en secreto, usas credenciales privadas del broker con TLS y registras cada comando. Evítalo para equipos críticos para la seguridad que necesiten enclavamientos locales.