n8n-nodes-fluxo

Node community do n8n para a Fluxo Inteligente — WhatsApp pela Cloud API
oficial da Meta, com coexistência (o número continua no celular do dono e ao
mesmo tempo responde pela API).

Dois nodes:

• Fluxo WhatsApp — 35 ações sobre mensagens, conversas, instâncias, modelos
  e utilidades. Lista completa abaixo.
• Fluxo WhatsApp Trigger — recebe os eventos entregues pela plataforma
  (message.received, message.status, instance.status_changed,
  instance.access_expiring), com verificação de assinatura.

Instalação

No n8n self-hosted: Settings → Community nodes → Install, e informe
n8n-nodes-fluxo.

Manual, para desenvolvimento:

pnpm install
pnpm build
# torna o pacote visível para o n8n local
pnpm link --global
cd ~/.n8n/nodes && pnpm link --global n8n-nodes-fluxo

Ações

Mensagem (15) — Enviar Texto · Enviar Imagem · Enviar Documento · Enviar Áudio ·
Enviar Vídeo · Enviar Texto Longo · Enviar Em Lote · Enviar Modelo · Responder ·
Marcar Como Lida · Listar · Contar Por Status · Últimas Do Contato ·
Aguardar Entrega · Reenviar Falhadas

Conversa (10) — Listar · Listar Não Lidas · Listar Com Janela Aberta ·
Listar Paradas · Listar Mensagens · Buscar Por Telefone · Contar ·
Exportar Transcrição · Verificar Janela · Marcar Como Lida

Instância (4) — Listar · Obter · Verificar Saúde · Testar Conexão

Modelo (5) — Listar · Obter · Listar Campos · Pré-Visualizar ·
Validar Preenchimento

Utilidade (1) — Validar Número

Nem toda ação é um endpoint. A API tem 12 rotas; o resto são composições feitas
no node, e vale saber quais para não se surpreender com o custo:

• Buscar Por Telefone, Listar Não Lidas, Listar Com Janela Aberta,
  Listar Paradas, Contar e Últimas Do Contato paginam a lista de
  conversas e filtram localmente — a API não expõe esses filtros como query.
• Aguardar Entrega faz consultas repetidas até o status sair de queued.
• Reenviar Falhadas cruza mensagens com conversas para descobrir o
  destinatário, já que a linha da mensagem guarda só o conversation_id.
• Contar Por Status consulta status a status, e a API devolve no máximo 200
  por consulta: ao bater esse teto, a resposta marca amostra_limitada.
• Pré-Visualizar, Validar Preenchimento e Validar Número não chamam
  a Meta — resolvem no próprio node, sem custo.

Credencial

No painel (apiw.fluxointeligenteia.com), em Credenciais de API, crie uma
chave. Guarde o segredo — ele aparece uma única vez.

O HMAC Secret não é enviado: cada requisição é assinada em HMAC-SHA256 sobre
v1 \n timestamp \n nonce \n MÉTODO \n caminho \n sha256(corpo), exatamente
como o backend remonta a string. Por isso não existe "API key no header" aqui,
e por isso o relógio da máquina do n8n precisa estar sincronizado — o servidor
recusa carimbos fora de uma janela de 5 minutos.

Cada operação exige o escopo correspondente na credencial:

Duas coisas que decidem o envio

Janela de 24 h. Mensagem comum (Enviar) só sai se o contato escreveu nas
últimas 24 horas. Fora disso a API responde 422 window_closed e o caminho é
Enviar Modelo. O node de conversa devolve window_expires_at em cada
mensagem justamente para essa decisão.

Modelo é cobrado. Enviar Modelo abre conversa mesmo sem resposta do
contato e sempre gera cobrança. A resposta traz billable.

Em ambos, use a chave de idempotência quando o fluxo puder repetir: com a
mesma chave, a API devolve a mesma mensagem em vez de enviar — e cobrar — duas
vezes.

Trigger

A URL do webhook não é configurada pela API pública. Copie a URL de produção
do node e cole no painel, em Webhooks da instância; o segredo de assinatura
aparece na mesma tela e vai no campo Segredo do Webhook.

Sem o segredo o node aceita qualquer entrega — qualquer um que descubra a URL
dispara o fluxo. Com ele, a assinatura (timestamp \n corpo) e o carimbo são
conferidos.

Eventos de tipo não selecionado recebem 200 e são descartados: devolver erro
faria a plataforma tentar de novo por 24 h e marcar o webhook como falho.

Desenvolvimento

pnpm build       # tsc + ícones
pnpm typecheck
pnpm lint

A interface dos nodes é em português; as regras do eslint-plugin-n8n-nodes-base
que exigem inglês (title case, ponto final, "Get Many") estão desligadas em
.eslintrc.js. As regras estruturais continuam valendo.