Bot Telegram Node-RED pour appareils MQTT : alertes, état et commandes à distance

Associer Node-RED et Telegram vous offre un moyen gratuit et instantané de recevoir les alertes de vos appareils MQTT et de leur envoyer des commandes depuis votre téléphone. Dans ce tutoriel, vous allez créer un bot Telegram, le connecter à Node-RED, relayer des alertes de seuil depuis un topic MQTT, répondre à une commande /status avec la dernière mesure et commuter un relais avec /on et /off, tout en ignorant toute personne absente de votre liste d'autorisation.

Pourquoi Telegram convient bien aux notifications IoT

L'e-mail convient aux rapports, mais on le remarque tard et il finit facilement dans un filtre. Les bots Telegram sont gratuits à créer, les notifications push arrivent vite sur le téléphone, et la Bot API est bidirectionnelle : la conversation qui reçoit une alerte peut répondre par une commande. Pour une maison connectée ou un home lab, une serre, un petit atelier ou une équipe de maintenance d'astreinte, c'est souvent exactement le bon niveau d'outillage.

Node-RED est un bon hôte pour le bot, car il parle déjà MQTT nativement. Le bot ne communique jamais directement avec vos appareils. Il parle à Node-RED, et Node-RED publie et s'abonne sur le broker : vos appareils restent simples et ignorent totalement l'existence de Telegram.

Ce dont vous avez besoin

1. Une instance Node-RED en fonctionnement (en local, sur Raspberry Pi ou dans Docker).
2. Un compte Telegram.
3. Un broker MQTT. Ce guide utilise ConnectMQ ; pour les tests, nous utilisons le serveur MQTT public gratuit broker.connectmq.com avec le préfixe connectmq/demo/tg42x9. Remplacez tg42x9 par votre propre chaîne aléatoire.
4. Le paquet node-red-contrib-telegrambot.

Comme tout ce qui se trouve dans l'espace de démonstration public peut être lu par d'autres utilisateurs, n'y publiez pas de vraies commandes pour de vrais équipements. Passez à des identifiants privés avant de connecter quoi que ce soit d'important.

Étape 1 : créer le bot avec BotFather

Dans Telegram, ouvrez une conversation avec @BotFather et envoyez /newbot. Choisissez un nom d'affichage et un nom d'utilisateur se terminant par bot. BotFather répond avec un token d'API de la forme 123456789:AA.... Traitez-le comme un mot de passe : quiconque possède le token peut contrôler le bot.

Vous pouvez aussi envoyer /setcommands à BotFather et enregistrer la liste des commandes pour que Telegram affiche des suggestions :

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

Étape 2 : installer et configurer les nœuds Telegram

Installez node-red-contrib-telegrambot depuis Menu → Manage palette. Il ajoute trois nœuds que nous allons utiliser :

Créez un nœud de configuration du bot, collez le token et utilisez le mode polling par défaut. Le polling fonctionne derrière un NAT et une box Internet, car c'est Node-RED qui récupère les mises à jour auprès de Telegram au lieu d'attendre des connexions entrantes. Le nœud de configuration permet aussi de restreindre le bot à certains noms d'utilisateur ou chat IDs. Utilisez cette option, et ajoutez votre propre vérification dans le flow comme seconde couche.

Trouver votre chat ID

Reliez un nœud Telegram receiver à un nœud debug configuré pour afficher le message complet, déployez, puis envoyez un texte quelconque à votre bot. La barre latérale de debug affiche msg.payload.chatId. Notez-le : il vous servira pour la liste d'autorisation et pour envoyer des alertes non sollicitées.

Étape 3 : relayer les alertes MQTT vers Telegram

Le nœud sender attend que msg.payload soit un objet contenant un chat ID, un type et le contenu. Abonnez-vous à un topic d'alerte avec un nœud mqtt in (connectmq/demo/tg42x9/alerts/#) et convertissez chaque message avec un nœud 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;

Reliez-le à un nœud Telegram sender. Si vos alertes proviennent de valeurs brutes de capteurs plutôt que d'un topic d'alertes dédié, placez devant cette fonction la logique d'hystérésis et de temporisation de notre tutoriel d'alertes e-mail Node-RED, pour que le bot ne vous écrive pas à chaque mesure.

Étape 4 : répondre à /status avec les dernières valeurs

Conservez la dernière valeur de chaque capteur dans le contexte du flow. Abonnez-vous à connectmq/demo/tg42x9/sensors/# et stockez chaque mesure :

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;

Ajoutez ensuite un nœud Telegram command avec la commande /status, suivi de cette fonction et d'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;

Indiquer l'heure de la dernière mesure est important. Une valeur qui semble normale mais date de deux heures signale généralement que l'appareil est hors ligne.

Étape 5 : envoyer des commandes aux appareils MQTT

Ajoutez des nœuds Telegram command pour /on et /off. Tous deux alimentent un même nœud function qui vérifie l'expéditeur et construit deux messages : une commande pour l'appareil et une confirmation pour la conversation.

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];

Configurez la fonction avec deux sorties, reliez la première à un nœud mqtt out et la seconde à un Telegram sender. Si, dans votre version du nœud, le champ content ne contient pas le texte de la commande, utilisez deux nœuds function distincts, un par commande, avec l'état codé en dur. C'est moins astucieux, mais plus robuste.

Une meilleure réponse attend la confirmation de l'appareil. Faites publier par l'appareil son état réel sur connectmq/demo/tg42x9/relay1/state et relayez ce topic vers Telegram avec la fonction d'alerte de l'étape 3. Vous savez alors que le relais a bien commuté, et pas seulement qu'une commande a quitté Node-RED. Notre guide Node-RED HTTP vers MQTT utilise le même schéma commande-confirmation pour les appelants HTTP.

Tester la boucle complète

# 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"

Envoyez ensuite /status, /on et /off au bot et regardez les messages de commande apparaître dans le terminal de l'abonné.

Check-list de sécurité pour un bot Telegram Node-RED

Un bot capable de commuter un équipement est une télécommande : traitez-le comme tel.

1. Liste d'autorisation des chat IDs dans le nœud de configuration du bot, et de nouveau dans chaque fonction qui exécute une commande.
2. Gardez le token secret. Il se trouve dans les identifiants du nœud de configuration, pas dans le JSON du flow que vous exportez ou versionnez.
3. Utilisez des identifiants ConnectMQ privés et TLS (port 8883) pour tout ce qui dépasse la démo. Sur le serveur public, n'importe qui peut lire et publier sous n'importe quel topic de démonstration.
4. Rendez les commandes idempotentes. Envoyer /on deux fois doit laisser le relais allumé, pas le basculer.
5. Journalisez chaque commande avec le chat ID et l'heure, par exemple dans une base de données ou sur un topic d'audit retenu.
6. Protégez l'éditeur. Activez adminAuth dans settings.js pour que personne ne puisse modifier le flow ni la liste d'autorisation.

Dépannage

Faites tourner votre bot Telegram Node-RED sur ConnectMQ

Une fois le bot fonctionnel sur le broker de démonstration, basculez la configuration broker de Node-RED vers un broker MQTT managé privé ConnectMQ : port 8883 avec TLS, ainsi que le nom d'utilisateur, le mot de passe et le client ID générés dans le portail. Le client MQTT intégré au navigateur et l'explorateur de topics en direct du portail sont pratiques pour surveiller les topics de commande et d'état pendant que vous testez depuis votre téléphone. Inscrivez-vous à l'offre gratuite Serverless sur app.connectmq.com, sans carte bancaire. Si vous hésitez encore sur l'hébergement de votre broker, notre présentation du broker MQTT dans le cloud détaille les options, et le tutoriel Node-RED MQTT couvre le reste des bases de Node-RED.

Questions fréquentes

Quel paquet Node-RED utiliser pour Telegram ?

node-red-contrib-telegrambot est l'option la plus répandue. Il fournit des nœuds receiver, command et sender, prend en charge les modes polling et webhook, et peut restreindre l'accès à des utilisateurs ou des conversations connus.

Ai-je besoin d'une IP publique ou d'une redirection de port ?

Non. En mode polling, Node-RED effectue des requêtes sortantes vers Telegram, et MQTT est lui aussi une connexion sortante vers le broker : les deux fonctionnent derrière une box Internet.

Plusieurs personnes peuvent-elles utiliser le même bot ?

Oui. Ajoutez le chat ID de chaque personne à la liste d'autorisation, ou ajoutez le bot à un groupe et utilisez le chat ID du groupe pour les alertes.

Est-il sûr de piloter des appareils depuis Telegram ?

Cela peut l'être si vous restreignez les chat IDs, gardez le token secret, utilisez des identifiants broker privés avec TLS et journalisez chaque commande. Évitez-le pour les équipements critiques pour la sécurité qui exigent des verrouillages locaux.