O n8n conversa com a API de WhatsApp da ProxyBox por dois nós que já vêm instalados: o HTTP Request, para enviar, e o Webhook, para receber. Não é preciso nó de comunidade nem nada novo. Se preferir nós prontos em português, existe o pacote da ProxyBox para o n8n, com 8 modelos importáveis (instalação manual; em beta).
Este guia assume que você já tem uma instância Conectada e a chave (veja os primeiros passos). Lembre que a API não é a oficial da Meta e que o WhatsApp pode bloquear qualquer número: use um número que você possa perder.
Como guardo a chave no n8n?
Numa credencial do tipo Header Auth com o nome apikey, para a chave não ficar escrita no fluxo.
No n8n, crie uma credencial do tipo Header Auth com:
- Name:
apikey - Value: a chave da instância (
pbwa_…)
Assim a chave não fica escrita no fluxo.
Como envio uma mensagem?
Com um nó HTTP Request em POST https://proxybox.com.br/api/whatsapp/v1/messages/text e a credencial acima.
Adicione um nó HTTP Request com:
- Method: POST
- URL:
https://proxybox.com.br/api/whatsapp/v1/messages/text - Authentication: Generic Credential Type > Header Auth > a credencial acima
- Send Body: ligado, Body Content Type: JSON
- Specify Body: Using JSON, com:
{
"to": "{{ $json.telefone }}",
"text": "Olá, {{ $json.nome }}! Seu pedido {{ $json.pedido }} saiu para entrega."
}
Em Options > Headers, acrescente Idempotency-Key com um valor estável por mensagem (por exemplo, {{ $json.pedido }}-aviso-entrega), para o n8n não duplicar o envio se tentar de novo.
Ligue Settings > Retry On Fail com espera de 15 segundos. Tente de novo só quando a resposta for 429 ou 502.
Como respeito o ritmo de 10 por minuto?
Com um nó Loop Over Items (lote de 1) e um nó Wait de 8 segundos depois do envio.
O padrão é 10 mensagens por minuto. Se o fluxo envia para uma lista, coloque o nó Loop Over Items (lote de 1) e, depois do HTTP Request, um nó Wait de 8 segundos. É mais lento, mas evita o 429 e mantém o ritmo parecido com o de uma pessoa.
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 recebo as respostas?
Com um nó Webhook em POST, cuja Production URL você cola no aviso automático da instância.
- Adicione um nó Webhook (Method POST) e copie a Production URL. Ela precisa ser https e pública.
- No painel da instância, cole essa URL em Aviso automático, marque
Mensagem recebidae salve. - Ative o fluxo no n8n e use Testar aviso no painel. O Webhook deve receber o
webhook.test.
No nó Webhook, ligue Raw Body para ter o corpo exato, porque a assinatura é calculada sobre ele.
Como confiro a assinatura?
Com um nó Code logo depois do Webhook, que recusa o aviso sem assinatura válida.
Logo depois do Webhook, adicione um nó Code (JavaScript) que recusa avisos sem assinatura válida:
const crypto = require("crypto");
const segredo = $env.WA_SEGREDO; // o segredo do painel, em uma variável de ambiente
const cab = $input.first().json.headers["x-proxybox-signature"] || "";
const corpo = $input.first().binary?.data ? Buffer.from($input.first().binary.data.data, "base64").toString("utf8") : JSON.stringify($input.first().json.body);
const p = Object.fromEntries(cab.split(",").map((x) => x.split("=")));
const esperado = crypto.createHmac("sha256", segredo).update(`${p.t}.${corpo}`).digest("hex");
if (!p.v1 || esperado !== p.v1 || Math.abs(Date.now() / 1000 - Number(p.t)) > 300) {
throw new Error("Assinatura inválida");
}
return $input.all();
O ajuste do corpo depende de como o seu n8n entrega o corpo bruto; teste com o botão Testar aviso e confira se a assinatura bate antes de ligar o fluxo de verdade. Detalhes do formato estão no guia do aviso automático.
Fluxo 1: como envio com imagem?
Recurso em beta: pode mudar. Serve para mandar o comprovante, a foto do produto ou o QR de um ingresso.
- Um nó de entrada (planilha, formulário, banco) entrega
telefone,nomee o endereço da imagem emfoto. - O nó HTTP Request chama
POST https://proxybox.com.br/api/whatsapp/v1/messages/imagecom a credencial Header Auth e este corpo:
{
"to": "{{ $json.telefone }}",
"media": { "url": "{{ $json.foto }}" },
"caption": "Olá, {{ $json.nome }}! Segue a foto do seu pedido."
}
Se a imagem não tem endereço público (veio de um arquivo gerado no fluxo), passe antes por Extract From File (operação Move File to Base64 String) e use { "base64": "{{ $json.data }}", "mime": "image/png", "filename": "foto.png" }. Os limites de tamanho e de tipo estão em enviar mídia.
Fluxo 2: como respondo automaticamente?
- Webhook recebe
message.received. - Code confere a assinatura.
- IF deixa passar só
typeigual atext, e ignora os avisos de grupo (data.grouppreenchido) se você não quer responder nos grupos. - HTTP Request (ou seu CRM) busca o pedido do cliente pelo número
data.from. - HTTP Request em
POST /typingcom{ "to": "{{ $json.body.data.from }}", "state": "composing" }, seguido de um Wait de 2 segundos. - HTTP Request envia a resposta com
reply_toigual aodata.idda mensagem recebida, para a resposta aparecer citando a pergunta.
Responda o Webhook com 200 logo no início (opção Respond: Immediately) e deixe o resto do fluxo rodar depois. Dois cuidados: não responda a quem pediu para parar e não responda a mensagens enviadas pela própria instância (o evento message.sent). O "digitando…" do passo 5 é só conforto de leitura; não torna o número mais seguro.
Fluxo 3: como verifico o número antes de enviar?
Em listas feitas à mão, sempre há telefone errado. Verificar antes evita erro no envio e mantém a base limpa.
- Loop Over Items com lote de 50.
- HTTP Request em
POST /contacts/checkcom{ "numbers": {{ JSON.stringify($input.all().map(i => i.json.telefone)) }} }. A chamada pode levar mais de 15 segundos para 50 números; aumente o Timeout do nó para 90 segundos. - Code que junta o resultado com a lista original e mantém só
existsigual a verdadeiro, usando o camponumberdevolvido (ele já corrige o nono dígito). - HTTP Request de envio, seguido do Wait de 8 segundos.
O teto padrão é de 300 números verificados por dia por instância. Veja contatos. Se a verificação não fizer sentido para a sua lista, pule o fluxo.
Como recebo sem ter um endereço público?
Se o seu n8n roda em computador local ou atrás de firewall, use o modo de consulta em vez do Webhook. Ligue delivery_mode em pull e crie um fluxo com Schedule Trigger (a cada minuto) e um HTTP Request em GET https://proxybox.com.br/api/whatsapp/v1/events?after={{ $json.ultimo_id }}&limit=50; depois processe os itens de data.events e confirme com POST /events/ack. Guarde o último next_after nos dados estáticos do fluxo. O guia receber por consulta explica a espera de até 25 segundos e a confirmação.
Como respondo a botões e a mensagens seguidas?
- Botões: envie com
POST /messages/interactivee filtre o aviso comdata.typeigual abutton_reply, lendodata.selected.id. O envio dos botões foi provado em aparelho em 12/11/2026, mas o aviso do toque recebido não: aceite também texto. Lista e carrossel não funcionam e dão422 interactive_unsupported. Veja botões. - Mensagens seguidas: ligue o agrupamento e filtre
eventigual amessage.batch, para o fluxo rodar uma vez por conversa em vez de uma vez por mensagem. - Bot no n8n: o n8n também pode responder como bot da instância; veja bot por n8n ou webhook.
Quais são os erros comuns?
| Sintoma | Causa provável |
|---|---|
| 401 no envio | Chave errada ou trocada |
| 409 no envio | Instância desconectada; leia o QR de novo |
| 429 no envio | Passou do ritmo; use o nó Wait |
409 new_contacts_locked |
Trava de contato novo ligada; veja erros e limites |
422 media_unavailable |
O endereço da imagem não abriu ou o tipo não é aceito |
| O Webhook nunca recebe | URL de teste em vez da de produção, ou fluxo desativado |
| "Assinatura inválida" | Corpo já decodificado, em vez do bruto, ou segredo diferente |
Para usar proxy nas outras chamadas do fluxo, veja proxy no n8n.
Veja também
- Nós n8n para a API de WhatsApp: instalar
- Webhook da API de WhatsApp: eventos e assinatura
- 13 modelos para a API de WhatsApp (Woo, Asaas)
- Receber WhatsApp sem webhook e agrupar mensagens
Índice completo: documentação. Sobre o produto: conheça a API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra a versão 1.2 da API. Os fluxos não foram executados num n8n real.