Package Information
Documentation
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
- Suba o ZapGate e anote a URL pública (ex.:
https://zapgate.seudominio.com). - No n8n, crie credenciais ZapGate API:
- Base URL:
https://zapgate.seudominio.com(sem/api/v1) - Admin API Key: valor de
ZAPGATE_API_KEYno.envdo gateway - Instance ID: ID da instância no painel
- Base URL:
- Adicione o node ZapGate:
- Recurso: Mensagens → Operação: Enviar Texto
- Número:
5511999999999(DDI + DDD + número, só dígitos) - Texto: sua mensagem
- Execute o workflow.
Para parear WhatsApp: Recurso Sessão → Obter QR Code ou Obter Pair Code.
No pareamento por QR, escolha o Formato do QR: url (payload wa.me), base64 (data URL PNG) ou bin (PNG no campo binário data do item, só em Obter QR 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:
- Configure o webhook da instância no painel ou via Atualizar Instância (
webhook.urlapontando para um Webhook Trigger do n8n). - Eventos comuns:
message,connection,presence,history.sync, etc. - O evento
history.synctraz 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}comproxysalva 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
- Confirme que Admin API Key = valor exato de
ZAPGATE_API_KEYno servidor ZapGate. - Se usa Instance Token, verifique se não foi regenerado no painel.
- Instance ID deve corresponder à instância do token.
- Base URL sem
/api/v1no 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 (rodenpm run buildse instalou do source). - Em Docker, confirme
N8N_CUSTOM_EXTENSIONSapontando para a pasta custom.
Formato de número / chat
- Chat direto:
5511999999999(DDI + número, só dígitos). - Grupo: JID completo, ex.:
120363123456789012@g.us. - 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.