Pular para o conteúdo

Turbo Notify no Node-RED

Os nós do Turbo Notify para o Node-RED enviam mensagens de WhatsApp pelo seu próprio número (texto, imagem, vídeo, áudio, documento, figurinha, localização e respostas), leem em que pé está uma mensagem e iniciam um fluxo quando algo acontece no seu número, como a chegada de uma mensagem. Um sensor, um agendamento ou qualquer outro nó de um fluxo pode virar uma mensagem.

  • Uma conta do Turbo Notify com um número conectado (começo rápido).
  • Node-RED 3.0.0 ou mais novo, em Node.js 18 ou mais novo.
  • Uma chave de API, criada em API Keys (abre em nova aba) com o modelo Agente de IA (MCP), que cobre envio, leitura de mensagens, leitura de números (para o Test conferir se o seu número está vinculado) e leitura de eventos. Os escopos estão em Chave de acesso.
  1. Instale o pacote. No Node-RED, abra o menu, escolha Manage palette, depois Install, e procure por @turbo-notify/node-red-whatsapp. Ou, na pasta de usuário do Node-RED (normalmente ~/.node-red):

    npm install @turbo-notify/node-red-whatsapp

    Reinicie o Node-RED. Os nós aparecem na categoria Turbo Notify da paleta: whatsapp send, whatsapp status e whatsapp events.

  2. Arraste um nó whatsapp send para um fluxo e dê dois cliques nele. Ao lado de Account, clique no +: a janela repete as três coisas de que você precisa (conta, número de WhatsApp vinculado, chave de API), com links para cada tela do dashboard.

  3. Cole a sua chave e aperte Test. Ele diz em palavras simples se a chave funciona e se o seu número de WhatsApp está vinculado, e o que fazer se não estiver (um botão abre a página certa do dashboard). Clique em Add.

  4. Em To, coloque o seu próprio número de celular em formato internacional (+5511988887777).

  5. Ligue um nó inject com um texto como payload ao nó de envio e faça o deploy. Se você fizer o deploy antes de colar a chave, o nó mostra um paste your API key amarelo em vez de falhar na primeira mensagem.

O Node-RED entra com a chave de API. A chave fica no armazenamento de credenciais do Node-RED, então nunca aparece no arquivo do fluxo nem em um fluxo exportado, e só vai para o Turbo Notify, por https. O endereço da API não é uma configuração de um fluxo, então um fluxo que você importa ou recebe de alguém não pode escolher para onde a sua chave vai.

Aperte o botão do inject. O nó aceita a mensagem na hora e o WhatsApp a entrega um instante depois. Para acompanhar, ligue um nó whatsapp status depois do envio: ele lê o id da mensagem que o nó de envio deixa em msg.messageId e devolve pendente, enviada, entregue, lida ou falhou.

Para iniciar um fluxo quando chegar uma mensagem, use o nó whatsapp events. Por padrão ele escuta message.received, confere a cada 30 segundos e emite uma mensagem por evento, com o evento inteiro em msg.payload e o tipo em msg.topic. A primeira verificação depois do deploy só guarda a mensagem mais nova: as mensagens que chegaram antes do deploy não iniciam o fluxo. Para testar, faça o deploy, escreva para o seu número de outro telefone e espere até 30 segundos. Uma mensagem que cita outra chega como message.replied: os exemplos que respondem escutam os dois tipos, e nos seus próprios fluxos você pode escrever message.received,message.replied no campo Event types.

Há dezoito fluxos prontos para importar: no menu, Import, depois Examples, depois @turbo-notify/node-red-whatsapp. Cada um começa com uma nota chamada START HERE que repete os três passos de configuração e diz o que trocar. Troque o número de exemplo (+12025550123) antes do deploy, nos fluxos que têm um. Os fluxos que respondem às pessoas respondem a quem escreveu, então não têm número; o fluxo do grupo da equipe tem um id de grupo de exemplo para trocar.

  • Alertas de coisas: um sensor de porta, uma temperatura que passa de um limite (uma mensagem quando passa e outra quando volta ao normal), um site que sai do ar (uma mensagem quando cai e outra quando volta), um erro no próprio Node-RED e uma foto de câmera.
  • Mensagens agendadas: um lembrete nos dias úteis, um relatório diário para uma lista de pessoas (uma mensagem a cada 10 segundos), e a previsão do tempo de hoje toda manhã.
  • Mensagens dos seus sistemas: um endereço HTTP que envia uma mensagem quando outro sistema o chama, protegido por um token, e uma confirmação de pedido que escreve um resumo para o cliente.
  • Responder às pessoas: uma resposta a cada mensagem privada (no máximo uma por hora para cada pessoa), um menu que responde 1, 2 ou 3, uma resposta fora do horário enviada no máximo uma vez a cada 12 horas para cada pessoa, uma localização no mapa quando alguém pergunta onde você está, e o encaminhamento de mensagens privadas para um grupo da equipe (no máximo 5 por hora de uma mesma pessoa e 20 no total).
  • Documentos e conferência: um PDF com legenda, uma conferência de entrega que avisa se uma mensagem falhou, e um registro em CSV de toda mensagem que você recebe.

Em Manage palette, abra a aba Nodes e atualize o pacote, ou rode npm update @turbo-notify/node-red-whatsapp na pasta de usuário do Node-RED e reinicie.

Se você instalou a primeira versão, @turbo-notify/node-red-turbo-notify, desinstale-a e instale @turbo-notify/node-red-whatsapp. Os nós não mudaram, então os seus fluxos continuam funcionando.

  • O seu número envia uma mensagem por vez, com alguns segundos entre elas. Uma mensagem que espera mais de 5 minutos falha com message_timeout (ela ainda pode chegar), então um fluxo que envia uma lista longa pode perder as últimas mensagens. Um envio que chega antes do intervalo mínimo do plano (6 segundos no Free, veja Limites de envio) é recusado com 429 send_rate_spacing. Um fluxo que envia uma lista deve pôr um nó delay em modo de limitação de taxa (uma mensagem a cada 10 segundos) antes do nó de envio, como faz o exemplo do relatório diário.
  • Um ciclo é um mês da sua assinatura, e cada número tem uma cota de mensagens e de contatos por ciclo (plano Gratuito: 300 mensagens e 2 contatos, veja Cota e uso). Quando um limite é atingido nada é enviado em silêncio: o envio é recusado com messages_quota_exceeded (ou contact_quota_exceeded para um contato novo), o nó levanta esse erro com o código, e um nó Catch pode reagir, por exemplo mandando um e-mail para você. O envio volta quando o ciclo vira ou logo depois de uma mudança para um plano maior. O botão Test do nó da conta mostra o que você já usou e quando a contagem recomeça.
  • Qual número: um que já tem WhatsApp em um celular. O Turbo Notify o vincula do mesmo jeito que o WhatsApp Web, com um QR code ou um código de pareamento, e não cria a conta. Um chip de roteador ou de modem funciona se você conseguir registrar o WhatsApp nele (veja Números).
  • Os eventos são consultados, não empurrados: a cada 30 segundos por padrão, nunca mais rápido que a cada 10. A entrega é pelo menos uma vez, então guarde msg.payload.id se um fluxo nunca puder agir duas vezes no mesmo evento. Depois de um reinício, o contexto em memória padrão do Node-RED recomeça de agora; para manter a posição entre reinícios, configure um armazenamento de contexto persistente no settings.js.
  • A mídia é enviada de um endereço https público. O Node-RED não envia arquivo.
  • Enviar para um grupo exige o plano Empresarial ou superior.
  • O que foi executado: os nós foram carregados e exercitados nas imagens Docker do Node-RED 3.0.2, 3.1.15, 4.1.17 e 5.0.9 contra um substituto da API, e em 12 de novembro de 2026 o pacote, instalado do npm no Node-RED 4.1.17, foi usado com uma chave real: o botão Test do nó da conta passou, uma mensagem foi enviada e chegou a delivered, e o nó de eventos recebeu o evento message.sent. As telas do editor da versão 1.5.15 (a janela da conta, os estados do botão Test e a nota START HERE) foram percorridas em um editor Node-RED 4.1 de verdade contra o substituto da API. Não foi executado: essas telas com uma chave real.