Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Bots e IA

Bot por n8n ou webhook: seu fluxo ou seu servidor decide a resposta

A ProxyBox envia a mensagem assinada ao seu fluxo n8n ou servidor e usa a resposta como bot. Envelope, assinatura, formatos de resposta e limites.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Use type: "webhook" (ou "n8n") e o url do seu servidor ou do nó Webhook do n8n. A cada mensagem recebida, a ProxyBox faz um POST assinado com um envelope bot.message, e a resposta desse mesmo pedido ({"reply": "..."}, {"replies": [...]} ou {"actions": [...]}) é enviada pelo seu número. Resposta vazia (204) significa "não responder".

Recurso em beta: pode mudar. O formato do corpo que o nó Webhook do n8n entrega ao seu fluxo (body, headers, query) não foi conferido contra um n8n real.

Gatilhos, limites e proteções comuns estão na visão geral dos bots.

Situação: versão beta, em fase de testes.

Para que serve?

É o tipo mais livre. Em vez de a ProxyBox falar com uma plataforma pronta, você decide o que responder: consulta o pedido no seu banco, chama o seu CRM, passa por um modelo de IA de sua escolha, aplica regras de negócio e devolve o texto. Serve para quem usa n8n, Make, Zapier (com o gatilho de webhook), um servidor Laravel, Express ou Flask, e para plataformas que não têm tipo próprio (Langflow, Botpress e outras).

Como configuro?

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "enabled": true,
    "url": "https://n8n.suaempresa.com.br/webhook/whatsapp-bot",
    "api_key": "UM_TOKEN_SEU",
    "api_key_header": "X-Meu-Token",
    "signing_secret": "",
    "history_messages": 10,
    "send_history": true,
    "trigger": "all",
    "ignore_groups": true
  }'
Campo Para que serve
url Seu endereço https público
api_key Opcional: um token que a ProxyBox envia como Authorization: Bearer, ou no cabeçalho de api_key_header
signing_secret O segredo da assinatura; se deixar vazio, a ProxyBox gera um e mostra uma única vez
send_history Se verdadeiro, o envelope leva as últimas mensagens da conversa
history_messages Quantas (0 a 20)

Como é o pedido que o seu servidor recebe?

json
POST https://n8n.suaempresa.com.br/webhook/whatsapp-bot
Content-Type: application/json
X-ProxyBox-Signature: t=1794416769,v1=3f2a...e91c

{
  "event": "bot.message",
  "session": { "id": "bs_8f2c1d", "new": true },
  "chat": { "id": "5547999999999", "is_group": false, "name": "Maria" },
  "instance": { "slug": "atendimento-da-loja" },
  "text": "Qual o status do pedido 4512?",
  "messages": [ { "id": "3EB0A1", "type": "text", "text": "Qual o status do pedido 4512?" } ],
  "history": [ { "role": "user", "content": "Oi" }, { "role": "assistant", "content": "Olá! Como posso ajudar?" } ],
  "sent_at": "2026-11-12T10:00:00-03:00"
}
  • session.new é verdadeiro na primeira mensagem de uma sessão nova.
  • messages traz as mensagens do turno (mais de uma se você usa o agrupamento).
  • history (lista de role e content) só vem se send_history estiver ligado (o padrão é ligado) e houver conversa anterior.

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 confiro a assinatura?

O esquema é o mesmo do aviso automático: X-ProxyBox-Signature: t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do bot. Rejeite o pedido se a assinatura não bater ou se t estiver mais de 5 minutos distante. Um exemplo mínimo em Node:

js
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/whatsapp-bot", express.raw({ type: "application/json" }), async (req, res) => {
  const h = Object.fromEntries((req.header("x-proxybox-signature") || "").split(",").map((p) => p.split("=")));
  const ok = crypto.createHmac("sha256", process.env.BOT_SEGREDO).update(`${h.t}.${req.body.toString("utf8")}`).digest("hex") === h.v1
    && Math.abs(Date.now() / 1000 - Number(h.t)) < 300;
  if (!ok) return res.sendStatus(401);

  const ev = JSON.parse(req.body);
  res.json({ reply: `Recebi: ${ev.text}` });
});
app.listen(3000);

Que respostas a ProxyBox aceita?

Você devolve Efeito
{"reply": "texto"} Uma mensagem
{"replies": ["a", "b"]} Várias mensagens, em ordem
{"actions": [{"type":"text","text":"..."}, {"type":"image","url":"https://..."}, {"type":"end"}, {"type":"handoff"}]} Texto, imagem, encerrar a sessão (end) ou passar para uma pessoa (handoff)
Uma lista de itens, ou as chaves output, text ou message Aceitos, para facilitar o uso com nós do n8n
204 ou corpo vazio Não responder

O texto Workflow got started. (que o n8n devolve quando o nó Webhook está em Immediately) é recusado com aviso: o fluxo precisa responder com o resultado.

Como configuro o n8n?

  1. Crie um fluxo com o nó Webhook (POST). Em Respond, escolha When Last Node Finishes (ou use o nó Respond to Webhook).
  2. Cole a Production URL no campo url.
  3. Se quiser autenticar, ative Header Auth no nó Webhook com o mesmo nome e valor de api_key_header e api_key.
  4. Confira a assinatura em um nó Code (modelo no guia WhatsApp no n8n).
  5. No final do fluxo, devolva { "reply": "..." }.

O n8n entrega o corpo da chamada dentro de body (com headers e query ao lado); o seu fluxo deve ler {{$json.body.text}}. Esse formato segue o conhecimento do n8n e não foi conferido nesta rodada contra um n8n real. Se você usa o pacote de nós da ProxyBox, o gatilho dele cuida da assinatura.

Quais limites valem?

  • 15 segundos para responder (conexão de 5). Acima disso, é erro; se o seu fluxo é demorado, responda rápido com uma frase de espera e envie o resultado depois pela API.
  • Resposta de até 1 MB.
  • Endereço https público, sem redirecionamento.
  • As travas do número valem para a resposta: ritmo, não perturbe e trava de contato novo.
  • Máximo de 20 respostas por hora por conversa e 200 por dia.

E a memória?

Quem decide é você. Com send_history, o envelope traz as últimas mensagens; sem ele, o seu fluxo recebe só a mensagem atual e deve guardar o contexto do seu lado (por exemplo, no banco, pelo chat.id).

Erros comuns

Sintoma Causa provável
"Workflow got started." recusado Nó Webhook do n8n em Immediately
Estado error Assinatura recusada, resposta lenta, resposta não JSON
Respostas duplicadas O seu fluxo também envia pela API além de devolver reply
Nada acontece Gatilho keyword, grupo ignorado ou 204

Veja também

Índice completo: todos os guias. Sobre o produto: instância de WhatsApp com chave própria.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Fonte do formato do n8n: documentação pública do nó Webhook, lida em 11/11/2026. Recurso em beta.

Perguntas frequentes

Qual a diferença entre o tipo n8n e o tipo webhook?
Na prática, nenhuma no formato. Os dois recebem o mesmo envelope assinado e aceitam as mesmas respostas. O tipo n8n existe só para deixar claro, no painel, o que você está usando.
O n8n precisa responder no mesmo pedido?
Sim. A ProxyBox espera a resposta por até 15 segundos. No nó Webhook do n8n, use Respond: When Last Node Finishes (ou Using Respond to Webhook Node), nunca Immediately.
Posso responder com mais de uma mensagem?
Sim, com replies, uma lista de textos, ou com actions.

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