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

Como receber mensagens do WhatsApp sem endereço público?

Sem servidor público? Consulte GET /events com espera de até 25 s e confirme com POST /events/ack; reúna mensagens seguidas em message.batch. Beta.

12 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
No modo pull, a API não chama o seu sistema; ela guarda os avisos e você os busca com GET /events?after=<id>. Depois de processar, confirma com POST /events/ack {"up_to": <id>}. Com wait entre 1 e 25, a chamada espera até aparecer um aviso novo, o que dá resposta quase imediata sem manter conexão aberta. Os avisos ficam 7 dias. Mais abaixo, a seção sobre agrupar mensagens seguidas mostra como receber um único aviso message.batch depois de alguns segundos de silêncio.

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
bash
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).

bash
curl "https://proxybox.com.br/api/whatsapp/v1/events?after=0&limit=50" \
  -H "apikey: SUA_CHAVE"
json
{
  "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átis

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

bash
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_waiters com retry_after de 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.

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

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

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?

js
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 /events e o POST /events/ack nã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:

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

json
{
  "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 }
    ]
  }
}
  • text junta o texto de todas as mensagens, uma por linha.
  • messages mantém cada mensagem, na ordem, com id, type, text, timestamp e media (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?

js
// 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 com media.url se você guarda no S3).
  • buffer_replace exige 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

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

Perguntas frequentes

Preciso de um endereço https público para receber mensagens?
Não, se você usar o modo pull. O seu sistema pergunta à API quais avisos são novos, em vez de esperar que a API chame. Serve para quem roda em computador local, atrás de firewall ou em ambiente sem domínio.
Por quanto tempo os avisos ficam guardados?
Sete dias. Passou disso, o aviso não pode mais ser consultado, tenha sido confirmado ou não.
Dá para usar push e pull ao mesmo tempo?
Sim, com delivery_mode igual a both. A API entrega ao seu endereço e também guarda para consulta.
Quanto tempo o lote espera?
O tempo que você define, de 1 a 30 segundos, sem mensagem nova daquele chat. A espera máxima é de 3 vezes esse valor, contada a partir da primeira mensagem do lote.
O lote sai exatamente em N segundos?
Quase. Com o agendador da ProxyBox rodando, sai em N segundos mais cerca de 2; na folga entre execuções pode chegar a cerca de N mais 12 segundos. Não use o recurso para algo que dependa de precisão de segundo.
Perco mensagens se desligar o buffer com lote pendente?
Não. As mensagens esperam em banco, cifradas, e sobrevivem a reinício. Se o agendador parar, o lote sai quando ele voltar.

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