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

WhatsApp no n8n: enviar e receber com a API

Mande WhatsApp pelo n8n com o nó HTTP Request e receba pelo Webhook, com assinatura conferida e três fluxos prontos.

8 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Use o nó HTTP Request para enviar (POST /messages/text, com a chave numa credencial Header Auth) e o nó Webhook para receber, conferindo a assinatura. Este guia traz três fluxos prontos: enviar com imagem, responder automaticamente e verificar o número antes de enviar.

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:
json
{
  "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átis

Como recebo as respostas?

Com um nó Webhook em POST, cuja Production URL você cola no aviso automático da instância.

  1. Adicione um nó Webhook (Method POST) e copie a Production URL. Ela precisa ser https e pública.
  2. No painel da instância, cole essa URL em Aviso automático, marque Mensagem recebida e salve.
  3. 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:

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

  1. Um nó de entrada (planilha, formulário, banco) entrega telefone, nome e o endereço da imagem em foto.
  2. O nó HTTP Request chama POST https://proxybox.com.br/api/whatsapp/v1/messages/image com a credencial Header Auth e este corpo:
json
{
  "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?

  1. Webhook recebe message.received.
  2. Code confere a assinatura.
  3. IF deixa passar só type igual a text, e ignora os avisos de grupo (data.group preenchido) se você não quer responder nos grupos.
  4. HTTP Request (ou seu CRM) busca o pedido do cliente pelo número data.from.
  5. HTTP Request em POST /typing com { "to": "{{ $json.body.data.from }}", "state": "composing" }, seguido de um Wait de 2 segundos.
  6. HTTP Request envia a resposta com reply_to igual ao data.id da 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.

  1. Loop Over Items com lote de 50.
  2. HTTP Request em POST /contacts/check com { "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.
  3. Code que junta o resultado com a lista original e mantém só exists igual a verdadeiro, usando o campo number devolvido (ele já corrige o nono dígito).
  4. 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/interactive e filtre o aviso com data.type igual a button_reply, lendo data.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ão 422 interactive_unsupported. Veja botões.
  • Mensagens seguidas: ligue o agrupamento e filtre event igual a message.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

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

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