n8n-nodes-zapgate

Community node para n8n que expõe a API REST do ZapGate — gateway WhatsApp self-hosted com painel, inbox, webhooks, Chatwoot e IA.

Requisito: n8n self-hosted. Community nodes instalados manualmente não funcionam no n8n Cloud.

Índice

• Visão geral
• Instalação
• Início rápido
• Credenciais
• Autenticação por operação
• Referência de operações
• Envio de mídia
• Receber eventos (webhooks)
• Configuração da instância
• Exemplos de fluxos
• Solução de problemas
• Desenvolvimento
• Licença

Visão geral

Um único node ZapGate concentra 98 operações organizadas por recurso:

| Recurso | Exemplos | |---------|----------| | Mensagens | texto, mídia, áudio, localização, contato, enquete, status | | Sessão | QR code, pair code, conectar/desconectar, status | | Inbox (painel) | listar mensagens, marcar lidas, excluir conversas | | Grupos & Chat | criar grupo, participantes, presença, reações, arquivar | | Plataforma (admin) | métricas, templates, regras, entregas de webhook | | Chatwoot (admin) | config, teste, setup, sync, fila de jobs |

Outros destaques:

• Credenciais centralizadas (Base URL, Admin API Key, Instance ID, Instance Token)
• Mídia por URL, Base64 ou campo binário do item anterior
• Fallback automático de autenticação (Admin API Key → Instance Token em rotas de instância)
• Ícone oficial ZapGate

Documentação da API: painel do gateway em /docs (OpenAPI interativo).

Instalação

Opção A — pasta custom do n8n (recomendado)

mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm install /caminho/para/bxgatway/packages/n8n-nodes-zapgate
# após publicação no npm:
# npm install n8n-nodes-zapgate

Reinicie o n8n. O node ZapGate aparece na paleta ao buscar por "ZapGate".

Opção B — Docker Compose

Monte o pacote ou instale na pasta custom dentro do volume do n8n:

services:
  n8n:
    image: n8nio/n8n
    volumes:
      - n8n_data:/home/node/.n8n
      - ./packages/n8n-nodes-zapgate:/home/node/.n8n/custom/n8n-nodes-zapgate
    environment:
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom

Após o primeiro start, entre no container e rode npm install na pasta do pacote, ou copie o dist/ já compilado.

Opção C — UI do n8n (Community Nodes)

Em Settings → Community Nodes → Install, informe n8n-nodes-zapgate quando o pacote estiver publicado no npm.

Início rápido

1. Suba o ZapGate e anote a URL pública (ex.: https://zapgate.seudominio.com).
2. No n8n, crie credenciais ZapGate API:
   • Base URL: https://zapgate.seudominio.com (sem /api/v1)
   • Admin API Key: valor de ZAPGATE_API_KEY no .env do gateway
   • Instance ID: ID da instância no painel
3. Adicione o node ZapGate:
   • Recurso: Mensagens → Operação: Enviar Texto
   • Número: 5511999999999 (DDI + DDD + número, só dígitos)
   • Texto: sua mensagem
4. Execute o workflow.

Para parear WhatsApp: Recurso Sessão → Obter QR Code ou Obter Pair Code.

Credenciais

| Campo | Obrigatório | Descrição | |-------|-------------|-----------| | Base URL | Sim | URL pública do gateway. Ex.: https://zapgate.seudominio.com ou http://localhost:8081. Não inclua /api/v1. | | Admin API Key | Depende | Valor de ZAPGATE_API_KEY. Obrigatória para operações admin (instâncias, plataforma, Chatwoot). Também funciona em rotas de instância e não expira ao regenerar o token. | | Instance ID | Depende | ID da instância WhatsApp. Obrigatório para mensagens, grupos, chat, inbox, etc. | | Instance Token | Opcional | Token exibido no painel → aba API. Alternativa à Admin API Key para rotas de instância. Regenerar invalida o anterior. |

Dica: preencha Admin API Key + Instance ID — cobre praticamente todos os casos. Use Instance Token apenas se não quiser expor a chave admin no n8n.

Autenticação por operação

| Modo | Operações | Credencial exigida | |------|-----------|-------------------| | Nenhuma | GET /info, POST /auth/login | Apenas Base URL | | Admin | Instâncias, Plataforma, Chatwoot, logout | Admin API Key | | Instância | Mensagens, grupos, chat, inbox, sessão, etc. | Instance ID + (Admin API Key ou Instance Token) |

Em rotas de instância, se ambos Admin API Key e Instance Token estiverem preenchidos, o node tenta a Admin Key primeiro e faz fallback automático para o Instance Token em erro 401 recuperável.

Referência de operações

Informações & Autenticação

| Operação | Descrição | |----------|-----------| | Obter Informações | Health check e versão (GET /info) | | Login (API Key) | Valida ZAPGATE_API_KEY | | Logout | Encerra sessão admin |

Instâncias (admin)

| Operação | Descrição | |----------|-----------| | Listar / Criar / Obter / Atualizar / Excluir Instância | CRUD completo | | Regenerar Token | Gera novo Instance Token | | Listar / Limpar Logs | Logs da instância | | Testar Webhook | Dispara evento de teste | | Testar Proxy | Valida conectividade até web.whatsapp.com |

Sessão

| Operação | Descrição | |----------|-----------| | Conectar Sessão | Inicia pareamento | | Desconectar / Logout Sessão | Encerra sessão WhatsApp | | Obter QR Code / Obter Pair Code | Pareamento por QR ou código numérico | | Status da Conexão | Estado atual (conectado, desconectado, etc.) | | Foto de Perfil (própria / contato) | Download de avatar |

Inbox (painel)

| Operação | Descrição | |----------|-----------| | Listar Mensagens do Inbox | Mensagens cacheadas no painel | | Estado de Lidas / Marcar Chat como Lido | Controle de leitura | | Excluir Chat do Painel / Excluir Vários Chats | Remove do painel (opcional: apagar no WhatsApp) |

Histórico

| Operação | Descrição | |----------|-----------| | Status da Sincronização | Progresso pós-pareamento (history.sync) | | Cancelar Sincronização | Interrompe importação em andamento |

Mensagens

| Operação | Descrição | |----------|-----------| | Enviar Texto / Mídia / Áudio / Vídeo / Documento / Sticker | Envio com suporte a URL, base64 ou binário | | Enviar Localização / Contato / Enquete / Chave Pix / Botão Nativo | Tipos especiais (Pix = card nativo; Botão Nativo = copiar, link, etc.) | | Editar / Apagar Mensagem | Gerenciamento | | Baixar Mídia da Mensagem | Download de anexo (retorna base64) | | Publicar Status | Stories/status |

Usuários, Grupos, Chat, Perfil, Etiquetas, Canais

| Recurso | Destaques | |---------|-----------| | Usuários | Verificar números, info de usuários, listar contatos | | Grupos | CRUD, participantes, link de convite, foto, solicitações de entrada | | Chat | Presença, reação, temporárias, fixar, arquivar, silenciar, favoritar, apagar | | Perfil | Foto, recado, bloqueio, privacidade, presença | | Etiquetas | Criar/editar, etiquetar chat ou mensagem | | Canais | Listar, seguir, silenciar, enviar texto/mídia |

Plataforma (admin)

| Operação | Descrição | |----------|-----------| | Métricas da Instância / Snapshot da Plataforma | Observabilidade | | Listar Entregas de Webhook / Reenviar Webhook | Debug de webhooks | | Listar Templates / Enviar Template | Mensagens modeladas | | Listar Regras / Testar Regras | Motor de roteamento |

Chatwoot (admin)

| Operação | Descrição | |----------|-----------| | Obter Configuração / Testar Conexão / Configurar Inbox | Setup | | Sincronizar Webhook | Alinha eventos com Chatwoot | | Listar Jobs da Fila / Reprocessar Job | Fila de sincronização |

Envio de mídia

Operações com mídia exibem o campo Origem da Mídia:

| Origem | Quando usar | Campos | |--------|-------------|--------| | URL | Arquivo em link público (https://...) | URL | | Base64 / Texto | String base64 ou data URL | Base64, MIME Type, Nome do Arquivo | | Binário | Output de node anterior (Read Binary File, HTTP Request, etc.) | Nome do campo binário (padrão: data), MIME Type, Nome do Arquivo |

Para Base64 e Binário, informe MIME Type e Nome do Arquivo — o WhatsApp usa esses metadados para renderizar corretamente.

Receber eventos (webhooks)

Este pacote expõe operações de ação (chamadas à API). Para receber eventos do ZapGate no n8n:

1. Configure o webhook da instância no painel ou via Atualizar Instância (webhook.url apontando para um Webhook Trigger do n8n).
2. Eventos comuns: message, connection, presence, history.sync, etc.
3. O evento history.sync traz progresso da importação de histórico (active, progress, chunkOrder).

Use Testar Webhook (recurso Instâncias) para validar a URL antes de colocar em produção.

Configuração da instância

No node Atualizar Instância, envie um corpo JSON no campo Corpo JSON:

| Campo | Descrição | |-------|-----------| | syncFullHistory | Importar histórico completo após pareamento | | historySyncDays | Limitar importação aos últimos N dias | | importHistoryToChat | Gravar histórico no inbox do painel | | importHistoryToChatwoot | Enviar histórico importado ao Chatwoot | | ignoreNewsletter | Ignorar canais/newsletters no inbox | | proxy | Proxy HTTP/SOCKS5 por instância | | webhook, chatwoot, useMessageQueue, rateLimitPerMinute | Configurações operacionais |

Proxy

{
  "proxy": {
    "enabled": true,
    "protocol": "socks5",
    "host": "127.0.0.1",
    "port": 1080,
    "username": "",
    "password": ""
  }
}

• PATCH /instances/{id} com proxy salva e reconecta a instância pareada automaticamente.
• POST /instances/{id}/proxy/test (operação Testar Proxy) valida conectividade sem alterar a instância.

Chave Pix (card nativo)

Recurso Mensagens → Enviar Chave Pix

| Campo | Descrição | |-------|-----------| | Número | Destinatário (DDI + número) | | Nome do titular | Nome no card | | Chave Pix | Valor da chave | | Tipo da chave | PHONE, CPF, CNPJ, EMAIL ou EVP | | Instruções | Opcional |

Envia o card nativo do WhatsApp (ícone Pix + botão Copiar chave Pix). Não é cobrança.

Botão nativo (copy / url / call / reply)

Recurso Mensagens → Enviar Botão Nativo

Campos comuns: Número, Corpo da mensagem (obrigatório), Título e Rodapé (opcionais).

Escolha Tipo do botão — os campos extras mudam conforme o tipo:

| Tipo | Campos extras | Uso | |------|---------------|-----| | copy | Texto do botão, Texto a copiar | OTP, código de verificação | | url | Texto do botão, URL | Link de acesso, login | | call | Texto do botão, Telefone | Botão para ligar (com DDI) | | reply | Respostas (uma por linha) | Até 3 respostas rápidas |

Reply — formato das linhas: Texto|id (id opcional)

Sim|confirm_yes
Não|confirm_no

Exemplos de fluxos

Enviar código OTP com botão copiar

Webhook Trigger → ZapGate: Enviar Botão Nativo
  Tipo: copy
  Corpo: Seu código é {{ $json.code }}
  Texto a copiar: {{ $json.code }}

Compartilhar chave Pix

ZapGate: Enviar Chave Pix
  Nome do titular: Minha Empresa
  Chave: 61995768696
  Tipo: PHONE

Resposta automática a mensagem recebida

Webhook Trigger (POST) → IF (tipo = message) → ZapGate: Enviar Texto

Configure o webhook da instância ZapGate para a URL do trigger. No node ZapGate, use expressões n8n para mapear {{ $json.body.chat }} e o texto de resposta.

Encaminhar mídia recebida

Webhook Trigger → ZapGate: Baixar Mídia da Mensagem → ZapGate: Enviar Mídia (origem: Base64)

O download retorna base64 no JSON de saída — passe para o envio ou converta para binário com um node Convert to File.

Monitorar importação de histórico

Webhook Trigger (evento history.sync) → IF (progress = 100) → Notificação / próximo passo

Solução de problemas

HTTP 401 — credencial inválida

1. Confirme que Admin API Key = valor exato de ZAPGATE_API_KEY no servidor ZapGate.
2. Se usa Instance Token, verifique se não foi regenerado no painel.
3. Instance ID deve corresponder à instância do token.
4. Base URL sem /api/v1 no final.

"Instance ID não configurado"

Operações de mensagem, grupos, inbox e sessão exigem Instance ID nas credenciais, mesmo com Admin API Key preenchida.

"Campo binário não encontrado"

No envio por Binário, confira o nome do campo (padrão data) e se o node anterior produz dados binários no item.

Node não aparece após instalar

• Reinicie o n8n após npm install.
• Verifique se dist/ existe (rode npm run build se instalou do source).
• Em Docker, confirme N8N_CUSTOM_EXTENSIONS apontando para a pasta custom.

Formato de número / chat

• Chat direto: 5511999999999 (DDI + número, só dígitos).
• Grupo: JID completo, ex.: [email protected].
• Em grupos, use Número do remetente quando a operação exigir quem enviou a mensagem.

Desenvolvimento

cd packages/n8n-nodes-zapgate
npm install
npm run build    # compila TypeScript + copia ícone
npm run dev      # watch mode
npm run lint     # ESLint

Link simbólico na pasta ~/.n8n/custom apontando para este diretório (com dist/ compilado). Reinicie o n8n após cada build.

Estrutura:

n8n-nodes-zapgate/
├── credentials/ZapGateApi.credentials.ts   # credenciais
├── nodes/ZapGate/
│   ├── ZapGate.node.ts                   # node principal
│   ├── operations.ts                     # definição das 98 operações
│   └── GenericFunctions.ts               # HTTP client, mídia, auth
└── dist/                                 # saída publicada

Licença

MIT — veja o repositório zapgate/zapgate.