wacaller

Nodes do n8n para o WaCaller: envie mensagens de WhatsApp, faça ligações, gerencie grupos, comunidades e contatos, e receba eventos em tempo real.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.7
Author: WaCaller

Documentation

n8n-nodes-wacaller

Nodes do n8n para o WaCaller: mande mensagens de WhatsApp, faça ligações, crie grupos e comunidades, consulte contatos e receba eventos em tempo real (mensagem recebida, reação, voto em enquete, resposta de formulário…), tudo arrastando blocos, sem programar.

O pacote traz:

Node Para que serve
WaCaller Faz ações: enviar texto/foto/áudio/botões, ligar, criar grupo, verificar número…
WaCaller Trigger Começa um fluxo quando algo acontece no WhatsApp (ex.: chegou uma mensagem)

💡 O que é o WaCaller? É o servidor que conecta números de WhatsApp (as sessões) e oferece uma API para mensagens, chamadas de voz/vídeo, grupos etc. Cada sessão é um WhatsApp conectado pelo QR Code no painel do WaCaller.


Sumário

  1. Instalação
  2. Como criar a credencial
  3. Conceitos rápidos (sessão, número, ID de grupo)
  4. Exemplos passo a passo
  5. Todos os recursos e operações
  6. Gatilho: eventos disponíveis e campos
  7. ⚠️ Aviso importante: um webhook por sessão
  8. Dúvidas e problemas comuns

Instalação

Opção 1: pelo próprio n8n (mais fácil)

  1. No n8n, abra Configurações (⚙️, canto inferior esquerdo) → Community Nodes.
  2. Clique em Install a community node.
  3. Digite n8n-nodes-wacaller, marque a caixa de ciência dos riscos e clique em Install.
  4. Pronto: procure por WaCaller ao adicionar um node.

Essa opção só aparece para o dono (owner) da instância do n8n.

Opção 2: n8n em Docker (variável de ambiente)

Adicione no serviço do n8n (docker-compose / stack):

environment:
  - N8N_COMMUNITY_PACKAGES=n8n-nodes-wacaller

Reinicie o n8n. Em versões em que a variável não existe, use a opção 3.

Opção 3: npm (instalação manual)

Dentro do container/servidor do n8n:

cd ~/.n8n/nodes        # crie a pasta se não existir
npm install n8n-nodes-wacaller

Reinicie o n8n.


Como criar a credencial

Você precisa de 2 informações:

Campo O que colocar Onde achar
URL do Servidor O endereço do seu WaCaller, ex.: https://calls.seudominio.com É o mesmo endereço que você abre no navegador para ver o painel. Sem barra no final e sem /api (o node corrige sozinho se vier).
API Key A chave de acesso É o valor da variável WACALLS_API_KEY da stack/servidor do WaCaller. Peça para quem administra o servidor.

Passo a passo:

  1. No n8n, vá em Credentials → Add credential → procure WaCaller API.
  2. Preencha URL do Servidor e API Key.
  3. Clique em Save. O n8n testa a conexão chamando GET /api/sessions. Se aparecer ✅, está tudo certo.

Se o teste falhar:

  • 401 → API Key errada.
  • Não conecta → URL errada, ou o servidor está fora do ar.

Conceitos rápidos

  • Sessão = um número de WhatsApp conectado ao WaCaller. Nos nodes, o campo Sessão mostra uma lista assim: Atendimento — +5511999999999 (conectada). Se aparecer desconectada ou aguardando QR Code, abra o painel do WaCaller e conecte o número.
  • Número (campo "Para"): sempre com DDI + DDD + número, só dígitos: 5511999999999. Pode ter ou não o 9º dígito, pode ter espaços, +, traços: o node limpa sozinho.
  • Grupo: o "Para" também aceita o ID do grupo, que termina em @g.us (ex.: 120363000000000000@g.us). Descubra com Grupo → Listar.
  • Listas de números (participantes, disparos…): um por linha ou separados por vírgula.
  • ID da mensagem: toda mensagem tem um ID (ex.: 3EB0C767D26A1D8C5A2B). No gatilho ele vem em idMensagem; quando você envia, vem em id na resposta. Use para responder, reagir, editar ou apagar.

Exemplos passo a passo

1) Enviar uma mensagem de texto

  1. Crie um fluxo novo e adicione um gatilho qualquer (ex.: Manual Trigger).
  2. Adicione o node WaCaller.
  3. Configure:
    • Credential: a credencial criada acima.
    • Recurso: Mensagem · Operação: Enviar Texto
    • Sessão: escolha o número que vai enviar.
    • Para: 5511999999999
    • Texto: Olá! Esta é uma mensagem automática 🚀
  4. Clique em Test step. A resposta traz id (ID da mensagem), to e timestamp.

Dica: use expressões para mensagens personalizadas, ex.: Olá {{ $json.nome }}, seu pedido {{ $json.pedido }} saiu para entrega!

2) Receber uma mensagem e responder automaticamente

Pronto para importar: examples/responder-mensagem.json (no n8n: menu ⋯ → Import from File).

  1. Adicione o node WaCaller Trigger.
    • Sessão: o número que vai receber.
    • Eventos: Mensagem (Recebida ou Enviada).
    • Em Opções Adicionais, deixe Ignorar Mensagens Enviadas por Mim ligado (padrão). Isso evita o fluxo responder a ele mesmo em loop.
  2. Adicione o node WaCaller depois do gatilho:
    • Recurso: Mensagem · Operação: Enviar Texto
    • Sessão: {{ $json.sessao }} (a mesma que recebeu)
    • Para: {{ $json.responderPara }} (já vem certo: o número do contato, ou o grupo)
    • Texto: Oi {{ $json.nome }}! Recebi: "{{ $json.texto }}"
    • (Opcional) Opções Adicionais → Responder à Mensagem (ID): {{ $json.idMensagem }} para aparecer como resposta citada.
  3. Ative o fluxo (botão Active). Mande uma mensagem para o número e veja a resposta chegar.

Para responder conforme o conteúdo, coloque um node Switch ou IF entre os dois, olhando o campo texto (ex.: se contém "preço" → manda a tabela).

3) Disparar uma ligação

Fazer o telefone tocar (alguém atende pelo painel do WaCaller):

  • Recurso: Chamada · Operação: Ligar
  • Para (Telefone): 5511999999999 · Chamada de Vídeo: desligado
  • A resposta traz call.callId. Para desligar depois: Chamada → Encerrar Chamada com esse ID.

A conversa por voz precisa de alguém no painel (navegador). Para tocar um áudio gravado automaticamente, use o disparo abaixo.

Ligar e tocar um áudio gravado (lembrete, aviso, campanha com opt-in):

  • Operação: Disparo de Ligações com Áudio
  • Números: um por linha
  • Origem do Arquivo: Link (URL) → https://seusite.com/aviso.mp3 (ou Arquivo Binário do n8n)
  • A resposta traz campaignId. Consulte com Status do Disparo, ou receba o andamento no gatilho com o evento Disparo de Ligações.

Só fazer tocar (ex.: alerta): Ligação Fantasma toca por N segundos (máx. 30) e desliga sozinha.

⚠️ Ligue apenas para quem autorizou. Ligações em massa não solicitadas podem bloquear o número e violam LGPD/Anatel.

4) Criar um grupo e adicionar pessoas

  1. Node WaCaller → Recurso: Grupo · Operação: Criar
    • Nome do Grupo: Turma 2026
    • Participantes Iniciais: (opcional) um número por linha
  2. A resposta traz o ID do grupo em jid (ex.: 120363...@g.us).
  3. Adicione outro node WaCaller → Grupo → Adicionar Participantes:
    • ID do Grupo: {{ $json.jid }}
    • Participantes: 5511999999999, 5511888888888
  4. A resposta mostra o resultado de cada pessoa em participants (quem falhou vem com error, ex.: 403 = a pessoa não permite ser adicionada).
  5. Quer o link de convite? Grupo → Link de Convite.

5) Enviar um formulário nativo (WhatsApp Business)

O formulário nativo é aquele criado no app WhatsApp Business (Ferramentas comerciais → Formulários). Ele abre dentro do WhatsApp do cliente.

  1. Uma única vez: crie o formulário no app e envie para alguém pelo celular (o WhatsApp só informa o formulário a dispositivos conectados depois do primeiro envio).
  2. Node WaCaller → Recurso: Formulário → Listar Formulários Nativos para conferir se ele aparece (com flowId).
  3. Node WaCaller → Recurso: Mensagem → Enviar Formulário Nativo:
    • Para: o número (só conversa individual, não grupo)
    • Formulário: escolha na lista
    • Texto da Mensagem e Texto do Botão: personalize
  4. Para receber as respostas, use o WaCaller Trigger com o evento Resposta de Formulário: as respostas vêm no campo respostas ({ nome_do_campo: valor }).

Todos os recursos e operações

Mensagem

Operação O que faz Rota da API
Enviar Texto Texto com formatação, citação e menções POST /messages/text
Enviar Imagem Foto com legenda (URL ou binário) POST /messages/image
Enviar Vídeo Vídeo com legenda POST /messages/video
Enviar Áudio Áudio comum ou gravado na hora (PTT), melhor com .ogg (Opus) POST /messages/audio
Enviar Documento Arquivo com nome e legenda POST /messages/document
Enviar Figurinha WebP 512x512 (estática ou animada) POST /messages/sticker
Enviar Localização Ponto no mapa com nome e endereço POST /messages/location
Enviar Contato Um ou mais cartões de contato POST /messages/contact
Enviar Enquete Pergunta + opções (uma ou várias respostas) POST /messages/poll
Enviar Botões Até 3 botões de resposta POST /messages/buttons
Enviar Lista Menu de opções (aparece no celular) POST /messages/list
Enviar Formulário Nativo Formulário do WhatsApp Business POST /messages/native-form
Reagir Emoji numa mensagem (vazio remove) PUT /messages/react
Editar Corrige o texto de uma mensagem sua PUT /messages/edit
Apagar Apaga para todos DELETE /messages
Marcar como Lida Tique azul em uma ou várias mensagens POST /messages/seen
Mostrar "Digitando…" Digitando / gravando áudio / parar POST /messages/typing

Opções comuns no envio (em Opções Adicionais): responder/citar mensagem, mencionar pessoas (@), tipo do arquivo, e ID próprio da mensagem (reenviar com o mesmo ID não duplica: ótimo para fluxos com repetição).

Chamada

Operação O que faz Rota
Ligar Faz o destino tocar (voz ou vídeo, com gravação opcional) POST /calls
Encerrar Chamada Desliga pelo ID DELETE /calls/{id}
Ligação Fantasma Toca por N segundos e desliga POST /calls/fake
Disparo de Ligações com Áudio Liga para vários e toca um áudio/vídeo gravado POST /broadcast
Status do Disparo Quem atendeu, quem não atendeu GET /broadcast/{id}
Histórico de Chamadas Últimas 50 chamadas (1 item por chamada) GET /history

Grupo

Operação Rota
Criar POST /groups
Listar (1 item por grupo) GET /groups
Ver Informações GET /groups/{gid}
Listar Participantes GET /groups/{gid}/participants
Adicionar / Remover Participantes POST /groups/{gid}/participants/add · /remove
Promover a Admin / Rebaixar Admin POST /groups/{gid}/participants/promote · /demote
Link de Convite / Gerar Novo Link GET /groups/{gid}/invite · POST /groups/{gid}/invite/revoke
Entrar por Link POST /groups/join
Alterar Nome / Alterar Descrição PUT /groups/{gid}/subject · /description
Sair POST /groups/{gid}/leave

Comunidade

Operação Rota
Criar POST /communities
Listar GET /communities
Ver (com grupos) GET /communities/{cid}
Criar Grupo na Comunidade POST /communities/{cid}/groups
Vincular / Desvincular Grupos POST /communities/{cid}/groups/link · /unlink
Listar Membros GET /communities/{cid}/participants
Adicionar Membros POST /communities/{cid}/participants/add

Contato

Operação Rota
Verificar se Tem WhatsApp (resolve o 9º dígito) GET /contacts/check?phone=
Listar GET /contacts
Ver Informações GET /contacts/{numero}
Foto de Perfil GET /contacts/{numero}/picture
Bloquear / Desbloquear POST /contacts/{numero}/block · /unblock

Sessão

Operação Rota
Listar Sessões (credenciais SIP ficam de fora por padrão) GET /api/sessions
Ver Status (conectada: true/false) GET /api/sessions (filtrado pela sessão)

Formulário

Operação Rota
Listar Formulários Nativos GET /native-forms

Requisição Personalizada (avançado)

Chama qualquer uma das 179 rotas da API, com a autenticação já aplicada. Informe método, caminho (ex.: /api/sessions/{sid}/messages/pix; o {sid} é trocado pela sessão escolhida), parâmetros de query e corpo JSON.

📚 A documentação completa (Swagger) fica no seu próprio servidor: https://SEU-SERVIDOR/api-docs.html.

Todas as rotas acima ficam sob /api/sessions/{sid} (exceto as de sessão).


Gatilho (WaCaller Trigger)

Eventos

Opção no n8n Nome do evento Quando dispara
Mensagem (Recebida ou Enviada) message Qualquer mensagem nova, inclusive clique em botão/lista
Confirmação de Entrega/Leitura receipt Tiques de entregue/lido
Reação reaction Alguém reagiu com emoji
Mensagem Apagada deleted O contato apagou para todos
Voto em Enquete poll_vote Alguém votou
Resposta a Evento event_response "Vou / Talvez / Não vou"
Resposta de Formulário form_response Formulário preenchido
Participantes de Grupo group_participants Entrou, saiu, promovido, rebaixado
Visualização Única view_once Chegou foto/vídeo de visualização única
Gravação de Chamada recording Gravação pronta
Disparo de Ligações broadcast Andamento do disparo
Status da Sessão session_status Número desconectado
Restrição da Conta restriction WhatsApp limitou o alcance do número
Microfone do Contato (Chamada) call_peer_mute Contato mutou/desmutou
Mão Levantada (Chamada) call_hand_raise Contato levantou/baixou a mão

Deixe Eventos vazio para receber todos.

Campos que o gatilho entrega

Cada evento vira um item com campos fáceis de usar, mais o conteúdo original em data:

Campo Exemplo Descrição
evento message Nome do evento
eventoDescricao Mensagem (Recebida ou Enviada) Nome amigável
sessao 6458cca6... ID da sessão (use no node WaCaller para responder pela mesma)
dataHora 2026-10-15T13:00:00.000Z Quando aconteceu
de 5511999999999 Telefone de quem enviou/reagiu/votou
nome Maria Nome do perfil
texto Oi, quero um orçamento Texto da mensagem (ou legenda, ou o botão clicado)
tipo text, image, audio… Tipo da mensagem
idMensagem 3EB0C767D26A1D8C5A2B Para citar, reagir, marcar como lida
chat / ehGrupo ...@g.us / true Conversa de origem
responderPara 5511999999999 Use no campo "Para" para responder: já é o grupo quando a mensagem veio de grupo
data { ... } Payload original completo do WaCaller

Campos extras por evento: emoji (reação), opcoesEscolhidas (enquete), respostas (formulário), entraram/sairam/promovidos/rebaixados (grupo), status/motivo (sessão).

Opções do gatilho

  • Ignorar Mensagens Enviadas por Mim (padrão: ligado): evita loop quando o fluxo responde.
  • Ignorar Mensagens de Grupos: só conversas individuais.
  • Segredo (HMAC): o WaCaller assina cada envio (X-Webhook-Signature: sha256=<hex>) e o n8n recusa (HTTP 401) o que não tiver a assinatura certa.

⚠️ Aviso importante: um webhook por sessão

Cada sessão do WaCaller tem apenas UM webhook. Por isso:

  • Ao ativar um fluxo com o WaCaller Trigger (ou clicar em Listen for test event), o node guarda o webhook que estava configurado na sessão e coloca o do n8n no lugar.
  • Ao desativar, o node restaura o webhook anterior automaticamente.
  • O segredo (HMAC) do webhook anterior não pode ser restaurado, porque a API nunca devolve segredos. Se o webhook antigo usava segredo, configure-o de novo no painel depois de desativar o fluxo.
  • Dois fluxos com gatilho na mesma sessão brigam entre si: o último ativado vence. Use um único gatilho por sessão e distribua para vários caminhos com o node Switch (por evento, texto etc.).
  • Se a sessão estiver integrada ao Chatwoot nativo do WaCaller, isso não é afetado: a integração Chatwoot é separada do webhook.

Dúvidas e problemas comuns

Mensagem O que fazer
erro 401: unauthorized API Key errada na credencial.
erro 404: no such session A sessão escolhida não existe mais. Escolha outra.
erro 503: not paired O número está desconectado. Abra o painel do WaCaller e leia o QR Code.
erro 429 Muitas chamadas simultâneas na mesma sessão.
A lista de sessões vem vazia Confira a credencial e se há sessões criadas no painel.
Lista (menu) não aparece Listas só aparecem no celular; o WhatsApp Web não mostra.
Formulário não aparece em "Formulário" Envie-o 1 vez pelo celular (limitação do WhatsApp).

Usar com Agentes de IA do n8n: o node WaCaller pode ser conectado como ferramenta (tool) de um AI Agent (ex.: "envie uma mensagem para fulano").

Tratamento de erros: ative Settings → On Error → Continue no node para o fluxo seguir mesmo se um envio falhar; o item volta com o campo error explicando o motivo.


Desenvolvimento

npm install
npm run build   # compila TypeScript para dist/ e copia os ícones
npm run lint    # regras oficiais de nodes do n8n
npm test        # teste rápido com requisições simuladas (sem rodar o n8n)

Licença

MIT

Discussion