n8n-nodes-conexozenvo-gateway

Community node do n8n para o WhatsApp Gateway (Conexo Envo).
Permite enviar mensagens/mídia, gerenciar sessões e contatos, e reagir a mensagens recebidas via webhook.

Instalação

No seu n8n self-hosted: Settings → Community Nodes → Install e informe:

n8n-nodes-conexozenvo-gateway

Community nodes exigem n8n self-hosted (Docker/bare-metal) ou n8n.cloud Pro/Enterprise.

Credencial

Crie uma credencial WhatsApp Gateway API com:

• Base URL — a URL da sua instância (ex.: https://api.conexozenvo.com)
• API Key — chave gerada no painel (enviada no header X-Api-Key)

Use o botão Test para validar.

Nodes

WhatsApp Gateway (ação)

O campo Session aceita o nome ou o ID da sessão.

Extrair leads de grupo → banco de dados

O resource Group lê os membros de um grupo com nome + número para alimentar um CRM/banco.

• List Groups — lista os grupos da sessão (id, nome, tamanho). Use para descobrir o Group ID.
• Get Info — detalha um grupo com todos os participantes (phone, name, role).
• Get Leads — entrega um item por membro com { phone, name, role }. Por padrão só os que
  têm número (lead utilizável); ligue Include Without Number para incluir os anônimos (LID).

Nome: o número sempre vem; o nome aparece quando disponível — nome salvo na agenda →
senão nome público (pushname) → senão null. A resolução é mais completa em sessões com a
engine WWEBJS (whatsapp-web.js), que herda o catálogo do WhatsApp Web; no Baileys, os
nomes vêm do cruzamento com o diretório de contatos.

Workflow típico (criar banco de leads):

WhatsApp Gateway (Group · Get Leads)  →  Postgres / n8n Data Table (Insert)

Como o Get Leads já emite um item por lead, é só ligar a saída num node de banco e mapear
phone / name — sem precisar de Split Out.

Salvar contato na agenda

O resource Contact grava na agenda da conta do WhatsApp (não apenas no índice interno):

• Save Contact — cria/edita um contato. Campos: Number (país + DDD), First Name,
  Last Name (opcional) e Sync to Phone. Com Sync to Phone ligado, o contato também é
  salvo na agenda do aparelho; desligado, fica só na conta do WhatsApp.
• Remove Contact — remove o contato da agenda (campo Number).
• Block / Unblock — bloqueia ou desbloqueia o contato (campo Number or JID).

Funciona nas duas engines: Baileys (addOrEditContact, via app-state sync) e
whatsapp-web.js (saveOrEditAddressbookContact). A sessão precisa estar conectada (WORKING).

WhatsApp Gateway Trigger

Dispara o workflow quando o gateway envia um evento. No ativar/desativar do workflow,
o node registra/remove automaticamente um webhook no gateway (POST/DELETE /api/webhooks).

• Events — message, session.status ou * (todos)
• Session — opcional; vazio = todas as sessões
• Verify Signature — valida a assinatura HMAC-SHA512 (x-webhook-signature) de cada entrega

Formato do payload entregue (envelope):

{
  "id": "01J...",
  "timestamp": 1700000000000,
  "event": "message",
  "sessionId": "01J...",
  "session": "campanha1",
  "payload": {
    "keyId": "...",
    "chatJid": "5511999999999@s.whatsapp.net",
    "fromMe": false,
    "type": "text",
    "text": "Olá!",
    "timestamp": 1700000000
  },
  "engine": "baileys"
}

Desenvolvimento

npm install
npm run build      # tsc + copia ícones para dist/

Testar localmente num n8n: npm link no pacote e npm link n8n-nodes-conexozenvo-gateway
na pasta ~/.n8n, ou aponte N8N_CUSTOM_EXTENSIONS para o dist/.

Licença

MIT