zbenapi

n8n community node para ZBen API — gerenciamento de instâncias WhatsApp multi-tenant

Package Information

Released: this month

Downloads: 0 weekly / 0 monthly

Latest Version: 2.0.0

Author: Agência Tec Ben

Available Nodes

Documentation generating…

ZBen

Gerencie instâncias WhatsApp via ZBen API

Documentation

n8n-nodes-zbenapi

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

O que é este node?

O ZBen 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
ZBen API	servidor próprio (`zbenapi.agtb.dev`)

Instalação

Via interface do n8n (recomendado)

Acesse Settings → Community Nodes
Clique em Install
Digite n8n-nodes-zbenapi
Clique em Install
Reinicie o n8n se solicitado

Via terminal

npm install n8n-nodes-zbenapi

Configuração de Credenciais

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

Campo	Descrição	Exemplo
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 /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 ou dado binário	Instance ID, Para, Origem, Caption (opcional)
Enviar Vídeo	Envia vídeo via URL ou dado binário	Instance ID, Para, Origem, Caption (opcional)
Enviar Áudio	Envia áudio (MP3/OGG) via URL ou dado binário	Instance ID, Para, Origem
Enviar Documento	Envia arquivo via URL ou dado binário	Instance ID, Para, Origem, Nome do arquivo
Enviar Sticker	Envia sticker (WebP) via URL ou dado binário	Instance ID, Para, Origem
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: 120363001234567890@g.us

Origem Do Arquivo (Enviar Imagem, Vídeo, Áudio, Documento, Sticker)

Essas operações aceitam duas origens de mídia, selecionadas no campo Origem Do Arquivo:

Origem	Como funciona
URL	Informe uma URL pública no campo URL Da Mídia. O servidor ZBen baixa o arquivo e envia ao WhatsApp.
Dado Binário	Informe o nome da propriedade binária (padrão `data`) no campo Propriedade Binária. Use quando o arquivo vem de um node anterior, como HTTP Request, Read/Write Files From Disk ou Extract From File.

No Enviar Documento, se o campo Nome Do Arquivo for deixado em branco com origem "Dado Binário", o node usa automaticamente o nome do arquivo binário recebido.

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 120363XXXXXXXXXX@g.us. 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)
    │
    ▼
ZBen Node
    │  Lê: resource + operation
    │
    ├─ instances → executeInstances()
    ├─ messages  → executeMessages()
    ├─ groups    → executeGroups()
    ├─ profile   → executeProfile()
    └─ chatwoot  → executeChatwoot()
           │
           ▼
       zBenRequest()
           │  Obtém credenciais (apiKey)
           │  Monta headers: { apikey: "sk_..." }
           │  Chama helpers.httpRequest() (n8n 2.0+)
           │
           ▼
       ZBen 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] → [ZBen: Enviar Texto] → [Resposta OK]

Workflow: Criar grupo e adicionar contatos

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

Workflow: Verificar número antes de enviar

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

Sobre a ZBen API

O ZBen é 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

zbenapi

Package Information

Available Nodes

Documentation

n8n-nodes-zbenapi

O que é este node?

Requisitos

Instalação

Via interface do n8n (recomendado)

Via terminal

Configuração de Credenciais

Recursos e Operações

Instâncias

Mensagens

Campo "Para" (número de destino)

Origem Do Arquivo (Enviar Imagem, Vídeo, Áudio, Documento, Sticker)

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

Grupos

Group JID

Campo "Participantes"

Perfil

Configurações de privacidade (updatePrivacy)

Chatwoot

Campos para Salvar Configuração

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

Como funciona internamente

Tratamento de erros

Exemplos de uso

Workflow: Enviar notificação WhatsApp

Workflow: Criar grupo e adicionar contatos

Workflow: Verificar número antes de enviar

Sobre a ZBen API

Resposta padrão da API

Compatibilidade

Suporte

Licença

Discussion

zbenapiInstall

Package Information

Available Nodes

Documentation

n8n-nodes-zbenapi

O que é este node?

Requisitos

Instalação

Via interface do n8n (recomendado)

Via terminal

Configuração de Credenciais

Recursos e Operações

Instâncias

Mensagens

Campo "Para" (número de destino)

Origem Do Arquivo (Enviar Imagem, Vídeo, Áudio, Documento, Sticker)

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

Grupos

Group JID

Campo "Participantes"

Perfil

Configurações de privacidade (updatePrivacy)

Chatwoot

Campos para Salvar Configuração

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

Como funciona internamente

Tratamento de erros

Exemplos de uso

Workflow: Enviar notificação WhatsApp

Workflow: Criar grupo e adicionar contatos

Workflow: Verificar número antes de enviar

Sobre a ZBen API

Resposta padrão da API

Compatibilidade

Suporte

Licença

Discussion

zbenapi