Recurso em beta: pode mudar. O formato de cada aviso é o mesmo do aviso automático.
Atualização de 12/11/2026 (provado em aparelho real): a consulta de avisos (fila) foi provada pela API pública. O agrupamento de mensagens segue em beta.
Quando escolher pull em vez de webhook?
O aviso automático (push) é o melhor caminho quando o seu sistema tem um endereço https público. Mas há casos em que isso não existe ou não compensa:
- um script rodando no seu computador ou num servidor sem domínio;
- um ambiente atrás de firewall que só permite conexões de saída;
- um fluxo no n8n ou em outra ferramenta que você prefere acionar em horários definidos;
- o teste de uma integração antes de publicar qualquer endereço.
Em compensação, no pull o seu código precisa perguntar. A espera longa (wait) reduz o atraso sem exigir conexão aberta por WebSocket, que esta API não oferece.
Como escolho o modo de entrega?
Pelo ajuste delivery_mode, em PUT /instance/settings:
| Valor | O que acontece |
|---|---|
push (padrão) |
A API chama o seu endereço https, com assinatura e novas tentativas |
pull |
A API não tenta entregar; guarda para consulta |
both |
Os dois: entrega ao endereço e guarda para consulta |
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"delivery_mode": "pull"}'
Sem endereço cadastrado, pull e both guardam do mesmo jeito. Se você muda de push para pull com avisos ainda na fila de entrega, a API converte esses avisos em consulta: nada se perde.
Como consulto os avisos novos?
Com GET /events. O parâmetro after é o último id que você já viu (comece com 0) e limit vai de 1 a 100 (padrão 50).
curl "https://proxybox.com.br/api/whatsapp/v1/events?after=0&limit=50" \
-H "apikey: SUA_CHAVE"
{
"ok": true,
"data": {
"events": [
{
"id": 121,
"event": "message.received",
"uid": "in_3EB0B430B6F8F1D0E053AC120E0A9E5C",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:00:02-03:00",
"occurred_at": "2026-11-12T13:00:01Z",
"data": { "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "from": "5547999999999", "type": "text", "text": "Oi" }
}
],
"next_after": 121,
"has_more": false
}
}
O envelope é igual ao do webhook, com um id numérico que só cresce. Guarde next_after e use como after na próxima chamada. has_more verdadeiro diz que há mais avisos esperando: chame de novo sem esperar. A consulta só devolve avisos não confirmados da sua instância, dos tipos que você escolheu receber.
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 espero por um aviso novo sem ficar perguntando?
Acrescente wait, de 1 a 25 segundos. Se houver aviso, a resposta vem na hora; se não houver, a chamada fica aberta até aparecer um ou até o tempo acabar, e então devolve a lista vazia.
curl "https://proxybox.com.br/api/whatsapp/v1/events?after=121&wait=25" \
-H "apikey: SUA_CHAVE" --max-time 30
Cada espera ocupa uma conexão do servidor durante todo o tempo, por isso há regras:
- use entre 20 e 25 segundos; esperas curtas repetidas são piores para todo mundo;
- no máximo 3 esperas ao mesmo tempo por instância; a quarta recebe
429 too_many_waiterscomretry_afterde 2 segundos; - ajuste o tempo limite do seu cliente HTTP para um pouco mais que o
wait.
Posso receber por SSE, sem ficar perguntando?
Pode, em beta. GET /events/stream entrega os mesmos avisos de GET /events, empurrados assim que chegam, no formato text/event-stream. Cada conexão dura até 25 segundos: no fim, a ProxyBox manda event: reconnect e fecha, e o EventSource do navegador (ou da sua biblioteca) volta sozinho, retomando do último id pelo cabeçalho Last-Event-ID.
curl -N -H "apikey: SUA_CHAVE" "https://proxybox.com.br/api/whatsapp/v1/events/stream?after=0"
Cada aviso chega com id, event (o nome, como message.received) e data (o mesmo JSON de GET /events). Linhas que começam com : são só sinal de vida. O stream não confirma nada: depois de processar, chame POST /events/ack. Vale o mesmo limite de 3 conexões abertas por instância (junto com as esperas de GET /events) e exige o modo de entrega pull ou both.
Como confirmo o que já processei?
Com POST /events/ack, passando up_to, o maior id processado. Todos os avisos até esse número saem da fila de consulta.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/events/ack" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"up_to": 121}'
# {"ok":true,"data":{"acked":1}}
Confirme depois de processar, nunca antes. Se o seu programa cair no meio, na próxima chamada os avisos não confirmados voltam, e você processa de novo. Por isso o processamento deve ser seguro para repetição: use o campo uid como chave única e ignore o que já viu.
Como fica um laço completo em Python?
import os, time, requests
BASE = "https://proxybox.com.br/api/whatsapp/v1"
H = {"apikey": os.environ["WA_KEY"]}
vistos = set()
after = 0
while True:
try:
r = requests.get(f"{BASE}/events", headers=H,
params={"after": after, "limit": 50, "wait": 25}, timeout=35)
if r.status_code == 429:
time.sleep(int(r.json().get("retry_after", 2)))
continue
r.raise_for_status()
dados = r.json()["data"]
except requests.RequestException:
time.sleep(5)
continue
for ev in dados["events"]:
if ev["uid"] in vistos:
continue
vistos.add(ev["uid"])
print(ev["event"], ev["data"]) # troque pelo seu processamento
if dados["events"]:
after = dados["next_after"]
requests.post(f"{BASE}/events/ack", headers=H, json={"up_to": after}, timeout=15)
E em Node?
const base = "https://proxybox.com.br/api/whatsapp/v1";
const headers = { apikey: process.env.WA_KEY, "Content-Type": "application/json" };
let after = 0;
for (;;) {
try {
const r = await fetch(`${base}/events?after=${after}&limit=50&wait=25`, { headers, signal: AbortSignal.timeout(35000) });
if (r.status === 429) { await new Promise((ok) => setTimeout(ok, 2000)); continue; }
const { data } = await r.json();
for (const ev of data.events) console.log(ev.event, ev.data); // seu processamento
if (data.events.length) {
after = data.next_after;
await fetch(`${base}/events/ack`, { method: "POST", headers, body: JSON.stringify({ up_to: after }) });
}
} catch { await new Promise((ok) => setTimeout(ok, 5000)); }
}
O que a consulta não faz?
- Não substitui o histórico de conversas: depois de 7 dias o aviso some. Para ler mensagens antigas, use conversas e mídia recebida.
- Não existe WebSocket, SSE, fila RabbitMQ, SQS, NATS ou Kafka. O pull com espera longa e o webhook assinado cobrem os casos de uso mais comuns sem exigir infraestrutura persistente.
- O
GET /eventse oPOST /events/acknão aparecem na página de atividade, para não poluir o registro com consultas.
Se você precisa de mensagens seguidas do mesmo contato reunidas num só aviso, veja agrupar mensagens.
Como agrupo mensagens seguidas?
Resposta curta: com buffer_seconds entre 1 e 30 no ajuste da instância, as mensagens seguidas de um mesmo chat esperam e chegam ao seu sistema em um único aviso message.batch, depois de N segundos sem mensagem nova. Com buffer_replace igual a true, o aviso individual de cada mensagem deixa de ser enviado.
Recurso em beta: pode mudar. O agrupamento foi testado sem aparelho real. A precisão do tempo sob carga e o formato exato do aviso de cada mensagem recebida no aparelho ainda não foram provados.
Para que serve?
Gente escreve em pedaços. "Oi", "tudo bem?", "queria saber do pedido 4512" são três avisos; se o seu sistema (ou o seu bot de IA) responder a cada um, a conversa fica picotada, custa três chamadas e passa a impressão de uma máquina. O agrupamento espera a pessoa terminar e entrega tudo junto.
É útil para:
- bots e agentes de IA, que respondem melhor com a frase completa;
- sistemas de atendimento, que preferem um cartão por conversa;
- fluxos no n8n, em que cada aviso dispara uma execução que custa tempo.
Como ligo?
Com PUT /instance/settings:
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"buffer_seconds": 5, "buffer_replace": false}'
| Ajuste | Valores | Efeito |
|---|---|---|
buffer_seconds |
0 a 30 (0 desliga) | Quantos segundos sem mensagem nova encerram o lote |
buffer_replace |
true ou false (padrão) |
true: só o lote vai; false: o lote vai além dos avisos individuais |
Para receber o message.batch, o evento precisa estar marcado entre os avisos que você quer, no painel ou pelo seu receptor. Com buffer_replace ligado e o message.batch não marcado, os avisos individuais voltam a sair, para você não ficar sem nada.
Como é o aviso message.batch?
{
"event": "message.batch",
"uid": "bt_9c1e7a20d4",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:00:09-03:00",
"occurred_at": null,
"data": {
"chat": "5547999999999",
"from": "5547999999999",
"name": "Maria",
"count": 3,
"text": "Oi\ntudo bem?\nqueria saber do pedido 4512",
"messages": [
{ "id": "3EB0A1", "type": "text", "text": "Oi", "timestamp": "2026-11-12T13:00:00Z", "media": null },
{ "id": "3EB0A2", "type": "text", "text": "tudo bem?", "timestamp": "2026-11-12T13:00:02Z", "media": null },
{ "id": "3EB0A3", "type": "text", "text": "queria saber do pedido 4512", "timestamp": "2026-11-12T13:00:04Z", "media": null }
]
}
}
textjunta o texto de todas as mensagens, uma por linha.messagesmantém cada mensagem, na ordem, comid,type,text,timestampemedia(nulo se não há arquivo; quando há, traz o tipo, o nome e o tamanho, como no aviso comum).- Em grupo, o chat é o identificador do grupo; as mensagens de um grupo se agrupam todas juntas, não por participante.
Em que momento o lote sai?
Quando passam N segundos sem mensagem nova daquele chat, ou quando se completa o teto de 3 vezes N desde a primeira mensagem, o que vier primeiro. Quem fecha o lote é o agendador da ProxyBox (a cada minuto, e de 2 em 2 segundos enquanto há lote esperando, por cerca de 50 segundos) e também o próximo aviso da mesma instância.
Na prática:
- com o agendador rodando, o lote sai em N segundos mais cerca de 2;
- na folga entre execuções, pode chegar a cerca de N mais 12 segundos;
- se o agendador parar, o lote sai quando ele voltar, e nada se perde: as mensagens ficam em banco, cifradas.
Com o teto de 3×N, uma pessoa que escreve sem parar não prende o aviso para sempre.
Como fica o código que recebe?
// Express: recebe o aviso e responde 200 logo
app.post("/whatsapp", express.raw({ type: "application/json" }), (req, res) => {
if (!confere(req.header("x-proxybox-signature"), req.body.toString("utf8"), process.env.WA_SEGREDO)) return res.sendStatus(401);
res.sendStatus(200);
const ev = JSON.parse(req.body);
if (ev.event === "message.batch") {
const { chat, text, count } = ev.data;
console.log(`${count} mensagens de ${chat}:`, text);
}
});
A função confere está no guia do aviso automático. O mesmo evento chega pelo modo de consulta, com o mesmo formato.
E com os bots?
Os bots usam o mesmo mecanismo quando você liga a opção debounce: com buffer_seconds maior que zero, o bot responde ao lote e ignora o aviso individual. Sem buffer_seconds, o bot usa uma espera própria bem curta (1,5 segundo, no máximo 3) para juntar mensagens coladas. Sem debounce, cada mensagem é um turno de conversa.
Cuidados
- Não use um número alto de segundos sem necessidade. Quem espera 30 segundos por uma resposta acha que ninguém está lá. De 3 a 8 segundos atende a maioria dos casos.
- Mídia vai no lote como item em
messages; o arquivo se baixa pela rota de mídia recebida (ou vem commedia.urlse você guarda no S3). buffer_replaceexige receber o lote. Ele só suprime o aviso individual quando o lote realmente chega ao seu sistema, assinado e por push ou por pull.- O agrupamento não muda o que é recebido pelo WhatsApp; só o que é entregue a você.
Veja também
- Webhook da API de WhatsApp: eventos e assinatura
- Sandbox da API de WhatsApp: testar sem número
- Bots de WhatsApp pela API: tipos e limites
- WhatsApp no n8n: enviar e receber com a API
Índice completo: índice dos guias. Sobre o produto: contratar uma instância de WhatsApp.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra as operações events.list e events.ack da versão 1.2. Recurso em beta.