Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Integrações

Como instalar os nós n8n da API de WhatsApp?

Instale o pacote de nós n8n-nodes-proxybox-whatsapp por tgz, crie a credencial e importe 12 modelos de fluxo. Versão beta, em fase de testes.

7 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
O pacote n8n-nodes-proxybox-whatsapp traz dois nós, ProxyBox WhatsApp (89 operações em 11 recursos) e ProxyBox WhatsApp Trigger (recebe os avisos e confere a assinatura), além de 12 modelos de fluxo importáveis. Como ainda não está no npm, a instalação é manual: npm install do arquivo .tgz dentro de ~/.n8n/nodes e reinício do n8n.

Recurso em beta: pode mudar. O pacote tem 5.342 verificações automáticas (5.344 com o n8n-workflow real), 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_after do 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:

sh
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?

  1. No n8n, crie uma credencial ProxyBox WhatsApp API.
  2. O endereço base já vem com https://proxybox.com.br/api/whatsapp/v1.
  3. Cole a chave da instância (pbwa_…), que está na área Integrar do painel.
  4. Se for usar o gatilho, cole também o segredo dos avisos (ou informe-o no próprio gatilho).
  5. 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átis

Como 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?

  1. Adicione ProxyBox WhatsApp Trigger e escolha os eventos que iniciam o fluxo (padrão: mensagem recebida).
  2. Ative o fluxo e copie a URL de produção do gatilho.
  3. Cole essa URL em Aviso automático, no painel da ProxyBox, junto com o mesmo segredo.
  4. Use Testar aviso no painel. O gatilho recusa com 401 o 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

  1. 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.
  2. O modelo de Chatwoot usa três chamadas à API do Chatwoot escritas sem teste. Para a ponte pronta, veja Chatwoot.
  3. 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

Í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.

Perguntas frequentes

Posso instalar pela tela de nós da comunidade do n8n?
Ainda não. Essa tela só aceita o nome de um pacote do npm, e o nosso ainda não está publicado. Por enquanto a instalação é manual, pela pasta ~/.n8n/nodes, com o arquivo tgz.
Preciso do pacote para usar o n8n com a API?
Não. O nó HTTP Request e o nó Webhook já fazem tudo, como mostra o guia WhatsApp no n8n. O pacote traz os nós prontos em português, com a assinatura conferida e a retentativa tratadas.
Os modelos funcionam sem o pacote?
Eles usam os nós do pacote. Sem instalá-lo, o n8n não reconhece os nós da ProxyBox ao importar.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp