Bot do Telegram no Node-RED para dispositivos MQTT: alertas, consultas de status e comandos remotos

Combinar Node-RED e Telegram oferece uma forma gratuita e instantânea de receber alertas de dispositivos MQTT e de enviar comandos a eles pelo celular. Neste tutorial você vai criar um bot do Telegram, conectá-lo ao Node-RED, encaminhar alertas de limite de um topic MQTT, responder a um comando /status com a leitura mais recente e ligar e desligar um relé com /on e /off, ignorando todo mundo que não estiver na sua lista de permissões.

Por que o Telegram funciona bem para notificações de IoT

E-mail serve para relatórios, mas demora a ser notado e é fácil de cair em filtros. Bots do Telegram são gratuitos, as notificações push chegam rápido ao celular e a Bot API é bidirecional: o mesmo chat que recebe um alerta pode responder com um comando. Para um laboratório em casa, uma estufa, uma pequena oficina, uma fazenda ou uma equipe de manutenção de plantão, muitas vezes essa é exatamente a quantidade certa de ferramenta.

O Node-RED é um bom anfitrião para o bot porque já fala MQTT nativamente. O bot nunca conversa diretamente com os seus dispositivos. Ele conversa com o Node-RED, e o Node-RED publica e assina no broker, o que mantém os dispositivos simples e completamente alheios ao Telegram.

O que você precisa

1. Uma instância do Node-RED rodando (local, Raspberry Pi ou Docker).
2. Uma conta no Telegram.
3. Um broker MQTT. Este guia usa a ConnectMQ; para testes usamos o servidor MQTT público em broker.connectmq.com com o prefixo connectmq/demo/tg42x9. Substitua tg42x9 por uma string aleatória sua.
4. O pacote node-red-contrib-telegrambot.

Como tudo o que fica na área pública de demonstração pode ser lido por outros usuários, não publique ali comandos reais para equipamentos reais. Passe para credenciais privadas antes de conectar qualquer coisa importante.

Passo 1: criar o bot com o BotFather

No Telegram, abra uma conversa com o @BotFather e envie /newbot. Escolha um nome de exibição e um nome de usuário terminado em bot. O BotFather responde com um token de API no formato 123456789:AA.... Trate-o como uma senha: qualquer pessoa com o token pode controlar o bot.

Opcionalmente, envie /setcommands ao BotFather e registre a lista de comandos para que o Telegram mostre sugestões:

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

Passo 2: instalar e configurar os nós do Telegram

Instale o node-red-contrib-telegrambot em Menu → Manage palette. Ele adiciona três nós que vamos usar:

Crie um nó de configuração do bot, cole o token e use o modo padrão de polling. O polling funciona atrás de NAT e de roteadores domésticos porque o Node-RED busca as atualizações no Telegram em vez de esperar conexões de entrada. O nó de configuração também permite restringir o bot a nomes de usuário ou chat IDs específicos. Use esse recurso e adicione a sua própria verificação no fluxo como segunda camada.

Encontre o seu chat ID

Ligue um nó Telegram receiver a um nó debug configurado para mostrar a mensagem completa, faça o deploy e envie qualquer texto ao seu bot. A barra lateral de debug mostra msg.payload.chatId. Anote-o; você vai usá-lo na lista de permissões e para enviar alertas não solicitados.

Passo 3: encaminhar alertas MQTT para o Telegram

O nó sender espera que msg.payload seja um objeto com um chat ID, um tipo e o conteúdo. Assine um topic de alertas com um nó mqtt in (connectmq/demo/tg42x9/alerts/#) e converta cada mensagem com um nó function:

const CHAT_ID = 123456789;   // o seu chat ID da barra lateral de debug

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

// Topic como 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;

Ligue-o a um nó Telegram sender. Se os seus alertas vêm de valores brutos de sensores, e não de um topic de alertas dedicado, coloque a lógica de histerese e cooldown do nosso tutorial de alertas por e-mail no Node-RED antes desta função, para que o bot não mande mensagem a cada leitura.

Passo 4: responder a /status com os valores mais recentes

Guarde o último valor de cada sensor no contexto de fluxo. Assine connectmq/demo/tg42x9/sensors/# e armazene cada leitura:

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;

Depois adicione um nó Telegram command com o comando /status, seguido desta função e de um Telegram sender:

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

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 o horário da última leitura faz diferença. Um valor que parece normal, mas tem duas horas, geralmente indica que o dispositivo está offline.

Passo 5: enviar comandos para dispositivos MQTT

Adicione nós Telegram command para /on e /off. Os dois alimentam um único nó function que verifica o remetente e monta duas mensagens: um comando para o dispositivo e uma confirmação para o chat.

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

// O comando configurado no nó command indica qual deles disparou
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];

Configure a função com duas saídas, ligue a primeira a um nó mqtt out e a segunda a um Telegram sender. Se o campo content não contiver o texto do comando na sua versão do nó, use dois nós function separados, um por comando, com o estado fixo no código. É menos engenhoso e mais robusto.

Uma resposta melhor espera a confirmação do dispositivo. Faça o dispositivo publicar o estado real em connectmq/demo/tg42x9/relay1/state e encaminhe esse topic para o Telegram com a função de alerta do Passo 3. Assim você sabe que o relé mudou de estado, e não apenas que um comando saiu do Node-RED. Nosso guia de HTTP para MQTT no Node-RED usa o mesmo padrão de comando e confirmação para chamadores HTTP.

Teste o ciclo completo

# Acompanhe o topic de comandos
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-tg42x9 -v -t "connectmq/demo/tg42x9/#"

# Simule um sensor e um alerta
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"

Depois envie /status, /on e /off ao bot e veja as mensagens de comando aparecerem no terminal do assinante.

Checklist de segurança para um bot do Telegram no Node-RED

Um bot que liga e desliga equipamentos é um controle remoto, então trate-o como tal:

1. Lista de permissões de chat IDs no nó de configuração do bot e de novo em toda função que executa um comando.
2. Mantenha o token em segredo. Ele fica nas credenciais do nó de configuração, e não no JSON de fluxo que você exporta ou versiona.
3. Use credenciais privadas da ConnectMQ e TLS (porta 8883) para qualquer coisa além de uma demonstração. No broker público, qualquer pessoa pode ler e publicar em qualquer topic de demonstração.
4. Torne os comandos idempotentes. Enviar /on duas vezes deve manter o relé ligado, e não alterná-lo.
5. Registre todo comando com chat ID e horário, por exemplo em um banco de dados ou em um topic de auditoria retained.
6. Proteja o editor. Ative o adminAuth em settings.js para que ninguém possa alterar o fluxo e a lista de permissões.

Solução de problemas

Rode o seu bot do Telegram no Node-RED com a ConnectMQ

Quando o bot estiver funcionando no broker de demonstração, troque a configuração de broker do Node-RED para um broker privado da ConnectMQ: porta 8883 com TLS e o nome de usuário, a senha e o client ID gerados no portal. Com um broker MQTT gerenciado, você não precisa manter o broker por conta própria. O cliente MQTT no navegador e o explorador de topics ao vivo do portal ajudam a acompanhar os topics de comando e de estado enquanto você testa pelo celular. Cadastre-se no plano Serverless gratuito em app.connectmq.com, sem cartão de crédito. Se você ainda está decidindo onde o seu broker deve ficar, nossa visão geral do broker MQTT na nuvem explica as opções, e o tutorial Node-RED MQTT cobre o restante do básico do Node-RED.

Perguntas frequentes

Qual pacote do Node-RED devo usar para o Telegram?

O node-red-contrib-telegrambot é a opção mais usada. Ele oferece nós receiver, command e sender, suporta os modos polling e webhook e pode restringir o acesso a usuários ou chats conhecidos.

Preciso de IP público ou redirecionamento de portas?

Não. No modo polling, o Node-RED faz requisições de saída para o Telegram, e o MQTT também é uma conexão de saída para o broker, então os dois funcionam atrás de um roteador doméstico.

Várias pessoas podem usar o mesmo bot?

Sim. Adicione o chat ID de cada pessoa à lista de permissões, ou adicione o bot a um grupo e use o chat ID do grupo para os alertas.

É seguro controlar dispositivos pelo Telegram?

Pode ser, se você restringir os chat IDs, mantiver o token em segredo, usar credenciais privadas do broker com TLS e registrar todos os comandos. Evite isso em equipamentos críticos para a segurança que exigem intertravamentos locais.