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)

| Resource | Operações | |---|---| | Message | Send Text · Send Media (by URL) · Send Presence · Mark as Read · List Conversations · List Messages | | Session | List · Get · Get Health · Start · Stop · Restart · Logout · Set State (Guard-Rail) · Update Config | | Contact | Directory · Check Numbers · Save Contact · Remove Contact · Block · Unblock | | Group | List Groups · Get Info · Get Leads (nome + número) | | Guardrail | Get Config · Set Config |

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": "[email protected]",
    "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