n8n-nodes-zapben

Node comunitário do n8n para integração com a ZapBen API — plataforma multi-tenant de gerenciamento de instâncias WhatsApp com integração ao Chatwoot.

O que é este node?

O ZapBen node permite que você controle instâncias WhatsApp diretamente dos seus workflows no n8n. Com ele você pode:

• Criar, conectar e gerenciar instâncias WhatsApp
• Enviar mensagens de texto, imagem, vídeo, áudio, documentos, localização, contatos, enquetes e reações
• Gerenciar grupos: criar, adicionar/remover participantes, promover/rebaixar admins, obter link de convite
• Consultar e atualizar o perfil da instância
• Configurar e gerenciar a integração com o Chatwoot

Requisitos

| Item | Versão mínima | |------|---------------| | n8n | 2.0 ou superior | | Node.js | 18.x ou superior | | ZapBen API | servidor próprio (wzapben.agtb.dev) |

Instalação

Via interface do n8n (recomendado)

1. Acesse Settings → Community Nodes
2. Clique em Install
3. Digite n8n-nodes-zapben
4. Clique em Install
5. Reinicie o n8n se solicitado

Via terminal

npm install n8n-nodes-zapben

Configuração de Credenciais

Após instalar, configure uma credencial do tipo ZapBen API:

| Campo | Descrição | Exemplo | |-------|-----------|---------| | Server URL | URL completa do seu servidor ZapBen | https://wzapben.agtb.dev | | API Key | Chave de acesso (tenant ou instância) | sk_ten_... ou sk_ins_... |

Dica: Use uma API Key de tenant (sk_ten_) para ter acesso a todas as instâncias. Use uma API Key de instância (sk_ins_) para restringir o acesso a uma instância específica.

O n8n testará a conexão automaticamente ao salvar, consultando o endpoint /api/health.

Recursos e Operações

Instâncias

Gerencia as conexões WhatsApp (instâncias).

| Operação | Descrição | Parâmetros | |----------|-----------|------------| | Listar | Lista todas as instâncias do tenant | — | | Criar | Cria uma nova instância | Nome | | Obter Status | Retorna o status atual da instância | Instance ID | | Conectar (QR Code) | Inicia conexão e gera QR Code para escanear | Instance ID | | Gerar Código De Par | Gera código para parear sem QR (pair code) | Instance ID, Número de telefone | | Desconectar | Desconecta a instância do WhatsApp | Instance ID | | Logout | Faz logout completo (exige novo QR) | Instance ID | | Deletar | Remove a instância permanentemente | Instance ID |

Exemplo — Criar instância:

Resource: Instância
Operation: Criar
Nome: minha-instancia

Retorno típico:

{
  "success": true,
  "data": {
    "id": "uuid-da-instancia",
    "name": "minha-instancia",
    "status": "disconnected"
  }
}

Mensagens

Envia e gerencia mensagens em conversas individuais ou grupos.

| Operação | Descrição | Parâmetros principais | |----------|-----------|----------------------| | Enviar Texto | Envia mensagem de texto simples | Instance ID, Para, Texto | | Enviar Imagem | Envia imagem via URL | Instance ID, Para, URL, Caption (opcional) | | Enviar Vídeo | Envia vídeo via URL | Instance ID, Para, URL, Caption (opcional) | | Enviar Áudio | Envia áudio via URL (MP3/OGG) | Instance ID, Para, URL | | Enviar Documento | Envia arquivo via URL | Instance ID, Para, URL, Nome do arquivo | | Enviar Sticker | Envia sticker (WebP) via URL | Instance ID, Para, URL | | Enviar Localização | Envia pin de localização | Instance ID, Para, Latitude, Longitude, Nome (opcional) | | Enviar Contato | Envia cartão de contato | Instance ID, Para, Nome do contato, Número do contato | | Enviar Reação | Reage a uma mensagem com emoji | Instance ID, Para, Message ID, Emoji | | Enviar Enquete | Cria enquete com múltiplas opções | Instance ID, Para, Pergunta, Opções (vírgula), Múltipla escolha | | Marcar Como Lida | Marca uma mensagem como lida | Instance ID, Message ID | | Deletar Mensagem | Remove uma mensagem enviada | Instance ID, Message ID | | Editar Mensagem | Edita o texto de uma mensagem | Instance ID, Message ID, Novo Texto |

Campo "Para" (número de destino)

• Conversa individual: número com DDI+DDD, sem formatação. Ex: 5511999999999
• Grupo: JID do grupo. Ex: [email protected]

Opções avançadas (sendText, sendImage, sendVideo, sendAudio, sendDocument)

| Opção | Tipo | Padrão | Descrição | |-------|------|--------|-----------| | Delay (ms) | Número | 1200 | Atraso em milissegundos antes do envio | | Mencionar Todos (@All) | Booleano | false | Menciona todos em grupos com @all |

Exemplo — Enviar texto:

Resource: Mensagem
Operation: Enviar Texto
Instance ID: uuid-da-instancia
Para: 5511999999999
Texto: Olá! Esta mensagem foi enviada pelo n8n 🤖

Exemplo — Enviar enquete:

Resource: Mensagem
Operation: Enviar Enquete
Instance ID: uuid-da-instancia
Para: 5511999999999
Pergunta da Enquete: Qual sua preferência?
Opções da Enquete: Opção A, Opção B, Opção C
Respostas Múltiplas: false

A enquete exige mínimo de 2 opções separadas por vírgula.

Grupos

Gerencia grupos do WhatsApp onde a instância é participante.

| Operação | Descrição | Parâmetros | |----------|-----------|------------| | Listar Grupos | Lista todos os grupos da instância | Instance ID | | Obter Grupo | Retorna detalhes de um grupo | Instance ID, Group JID | | Criar Grupo | Cria um novo grupo | Instance ID, Nome, Participantes iniciais | | Sair Do Grupo | Remove a instância do grupo | Instance ID, Group JID | | Listar Participantes | Lista os participantes do grupo | Instance ID, Group JID | | Adicionar Participantes | Adiciona números ao grupo | Instance ID, Group JID, Participantes | | Remover Participantes | Remove números do grupo | Instance ID, Group JID, Participantes | | Promover a Admin | Promove participantes a administrador | Instance ID, Group JID, Participantes | | Rebaixar De Admin | Remove o status de admin dos participantes | Instance ID, Group JID, Participantes | | Obter Link De Convite | Retorna o link de convite atual | Instance ID, Group JID | | Revogar Link De Convite | Invalida o link de convite atual | Instance ID, Group JID |

Group JID

O JID de um grupo tem o formato [email protected]. Você pode obtê-lo usando a operação Listar Grupos e acessando o campo id de cada grupo no retorno.

Campo "Participantes"

Informe os números separados por vírgula, com DDI+DDD:

5511999999999, 5521888888888, 5531777777777

Perfil

Consulta e atualiza o perfil e as configurações de privacidade da instância WhatsApp.

| Operação | Descrição | Parâmetros | |----------|-----------|------------| | Obter Perfil Próprio | Retorna nome, status e foto da instância | Instance ID | | Obter Perfil De Contato | Retorna o perfil de um número específico | Instance ID, Número/JID | | Atualizar Nome | Altera o nome de exibição da instância | Instance ID, Novo nome | | Atualizar Status | Altera a bio/status da instância | Instance ID, Novo status | | Verificar Número | Verifica se um número existe no WhatsApp | Instance ID, Número | | Obter Privacidade | Retorna as configurações de privacidade | Instance ID | | Atualizar Privacidade | Atualiza configurações de privacidade | Instance ID, Configurações |

Configurações de privacidade (updatePrivacy)

| Configuração | Opções | Descrição | |-------------|--------|-----------| | Última Vez Online | all / contacts / none | Quem pode ver quando você esteve online | | Foto Do Perfil | all / contacts / none | Quem pode ver sua foto | | Status | all / contacts / none | Quem pode ver seu status |

Chatwoot

Configura e gerencia a integração bidirecional entre a instância WhatsApp e o Chatwoot.

| Operação | Descrição | Parâmetros | |----------|-----------|------------| | Obter Configuração | Retorna a config Chatwoot da instância | Instance ID | | Salvar Configuração | Cria ou atualiza a integração | Instance ID + campos de config | | Remover Configuração | Remove a integração Chatwoot | Instance ID | | Testar Conexão | Testa se as credenciais Chatwoot estão corretas | Instance ID | | Importar Mensagens | Importa histórico de mensagens para o Chatwoot | Instance ID | | Sincronizar Avatares | Atualiza fotos de perfil dos contatos no Chatwoot | Instance ID |

Campos para Salvar Configuração

| Campo | Obrigatório | Descrição | |-------|------------|-----------| | Chatwoot URL | Sim | URL da sua instalação Chatwoot. Ex: https://app.chatwoot.com | | API Token | Sim | Token de acesso da API do Chatwoot | | Account ID | Sim | ID da conta no Chatwoot (número inteiro) | | Inbox ID | Sim | ID da inbox WhatsApp no Chatwoot |

Opções avançadas da configuração

| Opção | Padrão | Descrição | |-------|--------|-----------| | Assinar Mensagens | false | Assina as mensagens com o nome do agente | | Conversa Pendente | false | Novas conversas iniciam como pendente | | Reabrir Conversa | true | Reabre conversas resolvidas ao receber nova mensagem | | Importar Contatos | true | Cria contatos no Chatwoot ao receber mensagens | | Importar Mensagens | false | Importa histórico após sincronização | | Limite De Dias Para Import | 30 | Quantos dias de histórico importar |

Como funciona internamente

n8n item(s)
    │
    ▼
ZapBen Node
    │  Lê: resource + operation
    │
    ├─ instances → executeInstances()
    ├─ messages  → executeMessages()
    ├─ groups    → executeGroups()
    ├─ profile   → executeProfile()
    └─ chatwoot  → executeChatwoot()
           │
           ▼
       zapBenRequest()
           │  Obtém credenciais (serverUrl + apiKey)
           │  Monta headers: { apikey: "sk_..." }
           │  Chama helpers.httpRequest() (n8n 2.0+)
           │
           ▼
       ZapBen API  (seu servidor)
           │
           ▼
       { json: resposta }  →  próximo node

Tratamento de erros

O node suporta o modo "Continue On Fail" do n8n. Quando ativado:

• Erros de API são capturados por item
• O fluxo continua para o próximo item
• O item com erro retorna { error: "mensagem do erro" }

Quando desativado (padrão), qualquer erro interrompe a execução e exibe a mensagem de erro no n8n.

Exemplos de uso

Workflow: Enviar notificação WhatsApp

[Trigger] → [Preparar dados] → [ZapBen: Enviar Texto] → [Resposta OK]

Workflow: Criar grupo e adicionar contatos

[Trigger]
    → [ZapBen: Criar Grupo]      (salva group_id)
    → [ZapBen: Adicionar Participantes]
    → [ZapBen: Enviar Texto para grupo]

Workflow: Verificar número antes de enviar

[Trigger com número]
    → [ZapBen: Verificar Número]
    → [IF: exists = true]
         → [ZapBen: Enviar Texto]
    → [ELSE]
         → [Log: número inválido]

Sobre a ZapBen API

O ZapBen é uma plataforma multi-tenant para gerenciamento de instâncias WhatsApp. Usa:

• Go + whatsmeow para conexão direta com WhatsApp (sem browser)
• Chatwoot como interface de atendimento ao cliente
• PostgreSQL + Redis para persistência e cache
• API Keys com dois escopos: sk_ten_* (tenant) e sk_ins_* (instância)

Resposta padrão da API

// Sucesso
{ "success": true, "data": { ... } }

// Erro
{ "success": false, "error": { "code": "...", "message": "..." } }

Compatibilidade

| Versão | Status | |--------|--------| | n8n 2.0+ | ✅ Compatível (usa NodeConnectionTypes.Main e helpers.httpRequest) | | n8n 1.x | ⚠️ Pode funcionar, não garantido |

Suporte

• Suporte: [email protected]
• Issues: https://github.com/SuporteAGTB/n8n-nodes-zapben/issues
• Servidor: https://wzapben.agtb.dev

Licença

MIT — Agência Tec Ben