Recurso em beta: pode mudar. O pacote tem 5.342 verificações automáticas (5.344 com o
n8n-workflowreal), mas nunca foi carregado dentro de um n8n de verdade: nem o editor nem a execução de um fluxo foram provados. A estrutura segue a documentação do n8n, e o editor pode reclamar de algo que o carregador de testes não vê. Use primeiro numa instalação de teste.
Situação: versão beta, em fase de testes.
Pacote ou nó HTTP: qual escolho?
O guia WhatsApp no n8n mostra como usar só os nós que já vêm no n8n (HTTP Request e Webhook). Isso funciona hoje, sem instalar nada. O pacote acrescenta:
- Campos prontos em português para cada operação, com obrigatórios no alto e opcionais numa coleção;
- Mídia por URL, arquivo do n8n ou base64, com o limite de tamanho conferido antes de enviar;
- Retentativa tratada: espera o
retry_afterdo erro 429, repete nos 502/503 (nada saiu) e nunca repete o 504 (pode ter saído); - Gatilho com assinatura conferida em tempo constante, tolerância de 5 minutos e filtro de eventos;
- 12 modelos de fluxo.
Como instalo?
O n8n instala nós da comunidade pelo nome do pacote no npm. Como o nosso ainda não foi publicado, use o caminho manual, descrito na documentação do n8n:
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install https://proxybox.com.br/n8n/n8n-nodes-proxybox-whatsapp-0.2.0.tgz
Reinicie o n8n. Os dois nós aparecem ao pesquisar "ProxyBox". Se o n8n roda em Docker, entre no contêiner (docker exec -it n8n sh) e mantenha /home/node/.n8n em um volume, para a instalação sobreviver a atualizações. Se você tem o arquivo no computador, npm install /caminho/n8n-nodes-proxybox-whatsapp-0.1.0.tgz também funciona.
Pela tela do n8n (Configurações > Nós da comunidade > Instalar): só quando o pacote estiver no npm; então bastará digitar n8n-nodes-proxybox-whatsapp. Não há data prevista.
Como crio a credencial?
- No n8n, crie uma credencial ProxyBox WhatsApp API.
- O endereço base já vem com
https://proxybox.com.br/api/whatsapp/v1. - Cole a chave da instância (
pbwa_…), que está na área Integrar do painel. - Se for usar o gatilho, cole também o segredo dos avisos (ou informe-o no próprio gatilho).
- O botão de teste da credencial chama
GET /instance.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo uso o nó de ações?
Escolha o recurso (Mensagem, Conversa, Contato, Grupo, Etiqueta, Agendamento, Instância, Não perturbe, Atividade...) e a operação. Exemplo: Mensagem > Enviar texto, com Para e Texto. Pontos úteis:
- Chave de idempotência: preencha em todo envio (por exemplo, o número do pedido). A mesma chave em 24 horas devolve a resposta original sem enviar de novo, o que protege contra reexecução do fluxo.
- Agendar para: data e hora; sem fuso, vale o do fluxo. Uma mensagem por vez, até 30 dias.
- Dividir lista em itens: grupos, conversas e mensagens saem um por item.
- Baixar mídia recebida: devolve o arquivo como binário do n8n.
- Continuar em erro: o item sai com
{ ok:false, error, message, retry_after, http_status }.
| Resposta da API | O que o nó faz |
|---|---|
429 (rate_limited, daily_limit) |
espera o retry_after e repete (até 2 vezes, ajustável de 0 a 5) |
| 502 e 503 | repete; nada foi enviado |
retry_after maior que a espera máxima (60 s) |
falha mostrando o retry_after |
| 504 | nunca repete; confira antes de reenviar |
| 401, 403, 404, 409, 422, 501 | falha na hora |
Como uso o gatilho?
- Adicione ProxyBox WhatsApp Trigger e escolha os eventos que iniciam o fluxo (padrão: mensagem recebida).
- Ative o fluxo e copie a URL de produção do gatilho.
- Cole essa URL em Aviso automático, no painel da ProxyBox, junto com o mesmo segredo.
- Use Testar aviso no painel. O gatilho recusa com
401o que não tiver assinatura válida.
O gatilho confere a assinatura sobre os bytes originais do corpo (rawBody). Se o seu n8n estiver atrás de um proxy que reescreve o corpo, a assinatura não bate. A opção de não conferir existe só para teste. A saída é o envelope inteiro (event, uid, instance, sent_at, data); use o uid para não tratar um aviso duas vezes.
Quais são os 12 modelos?
Importe cada um pelo menu do n8n (Importar de arquivo) e escolha a sua credencial ao abrir.
| # | Modelo | O que faz |
|---|---|---|
| 1 | Resposta automática simples | Responde mensagens de texto |
| 2 | Atendimento com IA | Gatilho, agente de IA com memória por número e resposta |
| 3 | Verificar número antes de enviar | Confere se o número tem WhatsApp e só envia a quem tem |
| 4 | Fatura em PDF após pagamento | Recebe o aviso de pagamento e envia o PDF por URL, com idempotência |
| 5 | Lembrete agendado | Agenda uma mensagem para amanhã às 9h e lista as pendentes |
| 6 | Respostas de botão ou enquete em planilha | Pergunta com botões e grava as respostas no Google Sheets |
| 7 | Encaminhar para Chatwoot, Slack e Telegram | Copia cada mensagem recebida para os três |
| 8 | Backup diário de conversas | Todo dia grava as mensagens do dia anterior num arquivo |
| 9 | Bot com aprovação humana | Agente de IA que responde depois da aprovação de uma pessoa, com aviso à equipe |
| 10 | Status semanal com limite | Toda segunda às 9h publica um status, se estiver abaixo do limite de 24 h |
| 11 | Consulta de avisos em n8n local | Busca os avisos novos a cada minuto e confirma a leitura, sem expor o n8n à internet |
| 12 | Cobrança Asaas ou Hotmart | Recebe o aviso de cobrança (Asaas) ou compra (Hotmart) e manda a mensagem ao cliente |
Os modelos de IA, planilha, Slack, Telegram e Chatwoot pedem as suas credenciais. O arquivo .tgz e os modelos acompanham o pacote; baixe o arquivo .tgz (versão 0.2.0). Os modelos também estão em arquivos separados, na pasta https://proxybox.com.br/n8n/modelos-api-whatsapp/ (por exemplo 01-resposta-automatica-simples.json).
Limites desta versão beta
- Ao importar um modelo, o n8n pode pedir ajustes nos nós (IF, Set, Google Sheets, Slack, Telegram, HTTP, agente de IA), porque as versões de cada nó mudam.
- O modelo de Chatwoot usa três chamadas à API do Chatwoot escritas sem teste. Para a ponte pronta, veja Chatwoot.
- Botões: o envio foi provado em 12/11/2026, a resposta recebida não; lista e carrossel não funcionam (
interactive_unsupported). Veja botões.
Para quem prefere não instalar nada
Use o nó HTTP Request (veja o guia de n8n) e, para receber, o nó Webhook com o código que confere a assinatura. Ou deixe o n8n fora da ponta de recebimento: com o modo de consulta, o fluxo pergunta à API em vez de esperar um endereço público. Para fluxos prontos no formato HTTP, veja os modelos.
Veja também
- WhatsApp no n8n: enviar e receber com a API
- 13 modelos para a API de WhatsApp (Woo, Asaas)
- Bot de WhatsApp por n8n ou webhook próprio
- Webhook da API de WhatsApp: eventos e assinatura
Índice completo: todos os guias. Sobre o produto: planos e recursos da API de WhatsApp.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Fontes: documentação do n8n (criação de nós, credenciais, instalação manual) lida em 11/11/2026; relatório de verificação do pacote 0.2.0. Recurso em beta.