Package Information
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
- Instalação
- Como criar a credencial
- Conceitos rápidos (sessão, número, ID de grupo)
- Exemplos passo a passo
- Todos os recursos e operações
- Gatilho: eventos disponíveis e campos
- ⚠️ Aviso importante: um webhook por sessão
- Dúvidas e problemas comuns
Instalação
Opção 1: pelo próprio n8n (mais fácil)
- No n8n, abra Configurações (⚙️, canto inferior esquerdo) → Community Nodes.
- Clique em Install a community node.
- Digite
n8n-nodes-wacaller, marque a caixa de ciência dos riscos e clique em Install. - 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:
- No n8n, vá em Credentials → Add credential → procure WaCaller API.
- Preencha URL do Servidor e API Key.
- 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 emidMensagem; quando você envia, vem emidna resposta. Use para responder, reagir, editar ou apagar.
Exemplos passo a passo
1) Enviar uma mensagem de texto
- Crie um fluxo novo e adicione um gatilho qualquer (ex.: Manual Trigger).
- Adicione o node WaCaller.
- 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 🚀
- Clique em Test step. A resposta traz
id(ID da mensagem),toetimestamp.
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).
- 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.
- 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.
- Recurso:
- 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(ouArquivo 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
- Node WaCaller → Recurso:
Grupo· Operação:Criar- Nome do Grupo:
Turma 2026 - Participantes Iniciais: (opcional) um número por linha
- Nome do Grupo:
- A resposta traz o ID do grupo em
jid(ex.:120363...@g.us). - Adicione outro node WaCaller →
Grupo→Adicionar Participantes:- ID do Grupo:
{{ $json.jid }} - Participantes:
5511999999999, 5511888888888
- ID do Grupo:
- A resposta mostra o resultado de cada pessoa em
participants(quem falhou vem comerror, ex.:403= a pessoa não permite ser adicionada). - 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.
- 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).
- Node WaCaller → Recurso:
Formulário→Listar Formulários Nativospara conferir se ele aparece (comflowId). - 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
- 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,textoetc.). - 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)