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

Aviso automático (webhook) da API de WhatsApp

Receba mensagens e estados no seu sistema: cada evento em JSON, formatos ProxyBox, Evolution e Z-API, assinatura HMAC em 4 linguagens e IP de saída.

18 min de leitura Atualizado em 14 de novembro de 2026

O aviso automático (webhook) é uma chamada que a ProxyBox faz ao seu sistema quando algo acontece na instância: chegou uma mensagem, uma mensagem foi entregue ou lida, o número conectou ou desconectou. Assim o seu sistema não precisa perguntar o tempo todo. Este guia mostra como cadastrar o endereço, o JSON completo de cada evento, o formato opcional da Evolution e a conferência da assinatura em Node, Python, PHP e Go.

Cadastre o endereço

No painel, abra a instância, vá em Aviso automático para o seu sistema, digite o endereço (https://seu-sistema.com.br/whatsapp) e marque os avisos que quer receber. O painel confere o endereço antes de salvar e recusa o que não for seguro: http, endereço interno, porta fora do padrão, usuário e senha na URL.

Depois de salvar, use Testar aviso. O painel envia um aviso webhook.test assinado, mostra o código de resposta do seu sistema e guarda o resultado no histórico.

O que chega em cada aviso?

Resposta curta: um POST com corpo JSON, três cabeçalhos da ProxyBox e um envelope que sempre tem event, uid, instance, sent_at, occurred_at e data. O que muda de um evento para outro é só o data.

Cabeçalho Conteúdo
X-ProxyBox-Event O nome do evento, por exemplo message.received
X-ProxyBox-Delivery O uid do aviso (use para não processar duas vezes)
X-ProxyBox-Signature t=<unix>,v1=<hex>: hora e assinatura

Envelope, com o evento mais comum:

json
{
  "event": "message.received",
  "uid": "in_3EB0B430B6F8F1D0E053AC120E0A9E5C",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:05:01-03:00",
  "occurred_at": "2026-11-11T17:05:00Z",
  "data": {
    "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "from": "5547999999999",
    "name": "Maria",
    "type": "text",
    "text": "Oi, quero saber do pedido",
    "reply_to": null,
    "timestamp": "2026-11-11T17:05:00Z"
  }
}

sent_at é quando a ProxyBox entregou; occurred_at é quando o fato aconteceu (pode vir nulo). O uid é estável: o mesmo fato reenviado leva o mesmo uid. Os exemplos abaixo mostram o envelope completo de cada evento, com valores de exemplo. [Recurso em beta: pode mudar.] Os eventos de mensagem, estado e restrição já existiam na versão 1; os de grupo, reação, edição, exclusão, chamada e agendamento chegaram na 1.1; os de lote, voto, aprovação e as respostas de botão chegaram na 1.2 e estão em beta.

Quais eventos existem?

Evento Quando
message.received Chegou uma mensagem de um contato
message.sent Saiu uma mensagem da instância (inclusive as enviadas pelo celular)
message.status Entregue, lida ou ouvida
connection.updated Conectou ou desconectou
qr.updated QR novo para ler
number.logged_out O WhatsApp desconectou o aparelho
number.restricted O WhatsApp restringiu o número por um tempo
group.message.received e group.message.sent Mensagem recebida ou enviada num grupo
group.updated Alguém entrou, saiu, foi promovido ou o grupo mudou de nome
message.reaction, message.edited, message.revoked Reação, edição e exclusão para todos
call.received Chegou uma chamada
message.scheduled_failed Um envio agendado falhou de vez
message.batch Várias mensagens seguidas do mesmo chat, reunidas em um aviso (agrupar)
poll.vote Alguém votou numa enquete (provado em aparelho real em 14/11/2026)
presence.update Um contato que você assinou com POST /presence/subscribe ficou online ou offline (from, state, last_seen); beta
approval.requested e approval.decided Uma mensagem espera aprovação humana ou foi decidida

No painel você marca quais quer receber. Quem não está marcado não é entregue. Na prova em aparelho real de 10/11/2026, o motor entregou os avisos de mensagem (grupo termina em @g.us), reação, recibo de entrega e leitura (message.ack, que vira message.status) e chamada (call.offer, que vira call.received); a tradução para os nossos eventos segue o que o receptor faz.

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 é o JSON de cada mensagem?

Resposta curta: message.received e message.sent têm os mesmos campos, trocando from por to. O type diz o que veio e, quando há arquivo, media traz só mime, filename e size. O arquivo se baixa pela rota de mídia recebida.

type pode ser text, image, video, audio, voice, document, sticker, location, contact ou poll. Em text, o campo text é a mensagem; nos tipos com arquivo, é a legenda (pode ser vazio).

message.received com imagem e resposta a uma mensagem

json
{
  "event": "message.received",
  "uid": "in_3EB0A1",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:06:10-03:00",
  "occurred_at": "2026-11-11T17:06:09Z",
  "data": {
    "id": "3EB0A1",
    "from": "5547999999999",
    "name": "Maria",
    "type": "image",
    "text": "Segue o comprovante",
    "media": { "mime": "image/jpeg", "filename": null, "size": 183204 },
    "reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "timestamp": "2026-11-11T17:06:09Z"
  }
}

message.received com mensagem de voz (type voice, media.mime audio/ogg; codecs=opus) e com documento (type document, media.filename "contrato.pdf") têm a mesma forma.

message.received com localização

json
{
  "event": "message.received",
  "uid": "in_3EB0A2",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:07:00-03:00",
  "occurred_at": "2026-11-11T17:06:59Z",
  "data": {
    "id": "3EB0A2",
    "from": "5547999999999",
    "name": "Maria",
    "type": "location",
    "text": "",
    "location": { "latitude": -26.9194, "longitude": -49.0661, "name": null, "address": null },
    "reply_to": null,
    "timestamp": "2026-11-11T17:06:59Z"
  }
}

message.received com contato traz type igual a contact e contacts, uma lista de { "name": "Carlos", "phone": "5511988887777" }. Em enquete (poll), só o título chega em text; as opções e os votos não vêm no aviso.

message.sent
{
  "event": "message.sent",
  "uid": "out_3EB0C3",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:08:02-03:00",
  "occurred_at": "2026-11-11T17:08:01Z",
  "data": {
    "id": "3EB0C3",
    "to": "5547999999999",
    "type": "text",
    "text": "Pedido confirmado.",
    "timestamp": "2026-11-11T17:08:01Z"
  }
}

message.status muda status para delivered, read ou played (áudio ouvido). Vem um aviso por mensagem e por estado, só para conversas individuais:

json
{
  "event": "message.status",
  "uid": "st_3EB0C3_read",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:09:40-03:00",
  "occurred_at": "2026-11-11T17:09:39Z",
  "data": { "id": "3EB0C3", "to": "5547999999999", "status": "read", "timestamp": "2026-11-11T17:09:39Z" }
}

Como é o JSON de uma mensagem de grupo?

Resposta curta: igual ao da conversa individual, com group (id e name) a mais. Em group.message.received, from e name são do participante que escreveu; em group.message.sent, não há to.

json
{
  "event": "group.message.received",
  "uid": "gin_3EB0D4",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:10:00-03:00",
  "occurred_at": "2026-11-11T17:09:59Z",
  "data": {
    "id": "3EB0D4",
    "group": { "id": "[email protected]", "name": "Pedidos da semana" },
    "from": "5547999999999",
    "name": "Maria",
    "type": "text",
    "text": "Alguém viu o pedido 4512?",
    "reply_to": null,
    "timestamp": "2026-11-11T17:09:59Z"
  }
}

group.updated tem action com um destes valores: join (entrou), leave (saiu), promote, demote, joined (a própria instância entrou) ou name (o grupo mudou de nome). Os eventos de entrada, saída e promoção trazem participants (lista de telefones); name traz actor (quem mudou, pode ser nulo).

json
{
  "event": "group.updated",
  "uid": "gp_6c1f0b2a9d3e4f5a6b7c",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:11:00-03:00",
  "occurred_at": "2026-11-11T17:10:58Z",
  "data": {
    "group": { "id": "[email protected]", "name": "Pedidos da semana" },
    "action": "join",
    "participants": ["5511988887777"],
    "timestamp": "2026-11-11T17:10:58Z"
  }
}

Como são reação, edição, exclusão e chamada?

Os três primeiros têm um objeto comum: message_id (a mensagem afetada), chat (telefone da conversa ou id do grupo), from (quem agiu), from_me e timestamp. Em grupo, vem também group.

json
{
  "event": "message.reaction",
  "uid": "rx_3EB0E5",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:12:00-03:00",
  "occurred_at": "2026-11-11T17:11:59Z",
  "data": {
    "message_id": "3EB0C3",
    "emoji": "👍",
    "removed": false,
    "chat": "5547999999999",
    "from": "5547999999999",
    "from_me": false,
    "timestamp": "2026-11-11T17:11:59Z"
  }
}
  • message.reaction: emoji vazio e removed verdadeiro quando a pessoa tira a reação.
  • message.edited: acrescenta text com o texto novo.
  • message.revoked: acrescenta revoked_by_me (verdadeiro se foi a própria instância que apagou).
json
{
  "event": "call.received",
  "uid": "call_A1B2C3D4",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:13:00-03:00",
  "occurred_at": "2026-11-11T17:12:59Z",
  "data": {
    "call_id": "A1B2C3D4",
    "from": "5547999999999",
    "from_jid": "[email protected]",
    "name": "Maria",
    "auto_rejected": false,
    "platform": "android",
    "timestamp": "2026-11-11T17:12:59Z"
  }
}

call.received traz group se for chamada de grupo. Use o call_id em POST /calls/reject, ou ligue a recusa automática. from pode vir nulo quando o WhatsApp esconde o telefone (veja número e identidade).

Como são os avisos de estado da instância?

Resposta curta: quatro eventos: connection.updated (conectou ou desconectou), qr.updated (QR novo), number.logged_out (o WhatsApp tirou o aparelho) e number.restricted (restrição temporária).

json
{
  "event": "connection.updated",
  "uid": "cu_20261111140000_a1b2c3",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:14:00-03:00",
  "occurred_at": null,
  "data": { "status": "disconnected", "reason": "logged out" }
}

status é connected ou disconnected; reason é um texto curto (nulo quando conectou).

json
{
  "event": "number.restricted",
  "uid": "rb_9f3a0c1d2e4b5a69",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-11T14:15:00-03:00",
  "occurred_at": "2026-11-11T17:14:58Z",
  "data": { "reason": "reachout_timelock", "code": null, "expires_at": "2026-11-12T02:14:58Z" }
}

number.restricted liga a trava de contato novo. O guia restrição 463 explica o que fazer. number.logged_out traz reason e code (o código que o WhatsApp informou, quando existe). qr.updated traz expires_in, em segundos; o QR em si nunca viaja no aviso, só no painel e na rota GET /instance/qr.

json
{
  "event": "message.scheduled_failed",
  "uid": "sf_17_141600",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-12T09:16:00-03:00",
  "occurred_at": null,
  "data": { "schedule_id": 17, "op": "send.text", "to": "5547999999999", "error": "number_not_on_whatsapp", "message": "Esse número não tem WhatsApp." }
}

Quais valores status e reason posso receber?

Campo Valores
message.status.status delivered, read, played
connection.updated.status connected, disconnected
connection.updated.reason texto curto, como logged out; nulo se conectou
group.updated.action join, leave, promote, demote, joined, name
number.restricted.reason reachout_timelock ou o texto informado pelo WhatsApp
message.type text, image, video, audio, voice, document, sticker, location, contact, poll, button_reply (list_reply existe no formato, mas lista não funciona hoje)
approval.decided.status sent, rejected, expired, failed

Qual formato de aviso eu escolho: proxybox, evolution ou zapi?

Resposta curta: o padrão é proxybox, o envelope deste guia. Quem migra pode escolher, por instância, evolution ou zapi, e os mesmos fatos chegam nos nomes e na estrutura daquela API. A assinatura é sempre X-ProxyBox-Signature, calculada sobre o corpo que realmente sai. O formato zapi (ReceivedCallback, DeliveryCallback, MessageStatusCallback, ConnectedCallback e DisconnectedCallback) está descrito em migrar da Z-API; os nomes dos avisos de grupo e de chamada nesse formato ainda não foram conferidos contra a Z-API.

Como recebo no formato da Evolution?

Resposta curta: no painel, em Aviso automático, escolha format igual a evolution. Os mesmos fatos chegam com os nomes e a estrutura da Evolution v2, no envelope {event, instance, data, destination, date_time, sender, server_url, apikey}. O apikey vem sempre nulo; a validação é pelo cabeçalho X-ProxyBox-Signature, calculado sobre o corpo que realmente sai.

Aviso da ProxyBox event no formato evolution
message.received, group.message.received, message.reaction messages.upsert
message.sent, group.message.sent send.message
message.status messages.update
message.edited messages.edited
message.revoked messages.delete
connection.updated connection.update
qr.updated qrcode.updated (sem o QR)
group.updated group-participants.update, groups.upsert ou groups.update
call.received call
number.logged_out logout.instance
number.restricted, message.scheduled_failed o nome da ProxyBox, no mesmo envelope

A mesma mensagem recebida, no formato evolution:

json
{
  "event": "messages.upsert",
  "instance": "atendimento-da-loja",
  "data": {
    "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "3EB0A1" },
    "pushName": "Maria",
    "status": "DELIVERY_ACK",
    "message": { "imageMessage": { "mimetype": "image/jpeg", "fileLength": 183204, "caption": "Segue o comprovante" } },
    "contextInfo": { "stanzaId": "3EB0B430B6F8F1D0E053AC120E0A9E5C" },
    "messageType": "imageMessage",
    "messageTimestamp": 1794416769
  },
  "destination": "https://seu-sistema.com.br/whatsapp",
  "date_time": "2026-11-11T14:06:10-03:00",
  "sender": "[email protected]",
  "server_url": "https://proxybox.com.br/api/whatsapp/evolution",
  "apikey": null
}

Um aviso de conexão vira {"event":"connection.update","data":{"instance":"atendimento-da-loja","state":"open","wuid":"[email protected]","statusReason":200}}, e uma entrada em grupo vira {"event":"group-participants.update","data":{"id":"[email protected]","participants":["[email protected]"],"action":"add"}}, ambos dentro do mesmo envelope. O arquivo da mídia nunca vai junto: baixe pela rota de mídia recebida, ou use o S3 para receber o endereço. A caixa do nome do evento é minúscula com ponto (messages.upsert), como a Evolution envia no código; códigos que comparam com MESSAGES_UPSERT precisam ajustar. Mapa completo: migrar da Evolution.

O que mudou na versão 1.2?

Resposta curta: quatro acréscimos nos avisos: o type de resposta de botão e de lista, o endereço da mídia guardada no seu S3, o lote message.batch e os eventos de aprovação. O type de resposta de botão foi provado em aparelho real em 14/11/2026; o S3, o lote message.batch e os eventos de aprovação seguem em beta.

Resposta a botão. Quando alguém toca num botão de resposta enviado por POST /messages/interactive, deve chegar um message.received com type igual a button_reply e data.selected com o id e o text escolhidos (lista e carrossel não funcionam hoje, então não existe list_reply na prática):

json
{
  "event": "message.received",
  "uid": "in_3EB0F1",
  "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": "3EB0F1", "from": "5547999999999", "name": "Maria", "type": "button_reply", "text": "Confirmo", "selected": { "id": "sim", "text": "Confirmo" }, "reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C" }
}

O envio dos botões foi provado em aparelho real em 12/11/2026, mas o aviso do toque recebido ainda não foi provado: trate selected como opcional.

Mídia no seu armazenamento. Com o S3 ligado, data.media ganha url (link temporário de 24 horas ou público) e stored. Se o envio ao bucket falhar, url não vem e stored é false, e o aviso chega do mesmo jeito.

json
"media": { "mime": "image/jpeg", "filename": null, "size": 183204, "url": "https://meu-bucket.s3.amazonaws.com/whatsapp/atendimento-da-loja/2026/11/3EB0A1.jpg?X-Amz-...", "stored": true }

Lote de mensagens. Com buffer_seconds ligado, o aviso message.batch reúne as mensagens seguidas do mesmo chat:

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": 2,
    "text": "Oi\nqueria saber do pedido",
    "messages": [ { "id": "3EB0A1", "type": "text", "text": "Oi", "timestamp": "2026-11-12T13:00:00Z", "media": null }, { "id": "3EB0A2", "type": "text", "text": "queria saber do pedido", "timestamp": "2026-11-12T13:00:04Z", "media": null } ]
  }
}

Voto em enquete. poll.vote está na lista de eventos, com poll_id, voter, options e timestamp. Em 14/11/2026 um voto real foi entregue com o poll_id da enquete, o telefone de quem votou e a opção escolhida. O voto só chega quando a instância consegue ler a escolha por inteiro; se não conseguir, o aviso não é gerado. Por isso, não construa fluxo crítico só em cima dele.

Aprovação humana. approval.requested e approval.decided trazem approval_id, op, via e, na decisão, status (sent, rejected, expired ou failed) e decided_by. Nunca levam o texto da mensagem.

json
{
  "event": "approval.decided",
  "uid": "ad_41_sent",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-12T10:05:00-03:00",
  "occurred_at": null,
  "data": { "approval_id": 41, "op": "send.text", "status": "sent", "decided_by": "panel" }
}

De onde saem os avisos, e como libero no meu firewall?

Resposta curta: os avisos saem do endereço 209.222.97.88. Se o seu sistema só aceita conexões de IPs conhecidos, libere esse endereço (e, por precaução, confira a lista atual no painel, em Avisos, ou em /api-whatsapp/status?format=json, porque ela pode mudar). Bloquear o endereço faz os avisos falharem e entrarem no ciclo de novas tentativas.

E se eu não tenho endereço público?

Use o modo de consulta: o ajuste delivery_mode em pull guarda os avisos por 7 dias e você os busca com GET /events. Os envelopes são os mesmos deste guia, com um id numérico a mais. Veja receber por consulta. Com both, a ProxyBox entrega ao seu endereço e também guarda para consulta.

Confira a assinatura

A assinatura prova que o aviso veio da ProxyBox. O segredo aparece na página da instância, no bloco do aviso. Calcule o HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo e compare com o v1. Recuse se o t tiver mais de 5 minutos de diferença da hora do seu servidor.

import crypto from "node:crypto";

function confere(headerAssinatura, corpoBruto, segredo) {
  const partes = Object.fromEntries(headerAssinatura.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return false;
  const esperado = crypto.createHmac("sha256", segredo).update(`${partes.t}.${corpoBruto}`).digest("hex");
  const a = Buffer.from(esperado), b = Buffer.from(partes.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hmac, hashlib, time

def confere(header, corpo_bruto: bytes, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(partes["t"])) > 300:
        return False
    esperado = hmac.new(segredo.encode(), partes["t"].encode() + b"." + corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes.get("v1", ""))
function confere(string $header, string $corpoBruto, string $segredo): bool
{
    parse_str(str_replace(',', '&', $header), $p);
    if (abs(time() - (int) ($p['t'] ?? 0)) > 300) {
        return false;
    }
    $esperado = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $corpoBruto, $segredo);
    return hash_equals($esperado, $p['v1'] ?? '');
}
package wa

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"math"
	"strconv"
	"strings"
	"time"
)

func Confere(header string, corpoBruto []byte, segredo string) bool {
	partes := map[string]string{}
	for _, p := range strings.Split(header, ",") {
		if kv := strings.SplitN(p, "=", 2); len(kv) == 2 {
			partes[kv[0]] = kv[1]
		}
	}
	t, err := strconv.ParseInt(partes["t"], 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-t)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(segredo))
	mac.Write([]byte(partes["t"] + "."))
	mac.Write(corpoBruto)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(partes["v1"]))
}

Use sempre o corpo bruto da requisição, antes de decodificar o JSON: qualquer espaço a mais muda a assinatura.

Responda rápido e não repita

  • Responda 2xx em até 10 segundos. Se o processamento for longo, guarde o aviso numa fila e responda na hora.
  • Use o uid para deduplicar: se chegar de novo, ignore.
  • Não siga redirecionamento: os avisos não seguem. Cadastre o endereço final.
  • Se o seu sistema ficar fora do ar, a ProxyBox tenta de novo: depois de 1 minuto, 5 minutos, 15 minutos, 1 hora e 6 horas. Passadas as cinco tentativas, o aviso aparece como desistido no histórico, com o motivo, e o painel tem o botão Reenviar.
  • Se 10 avisos seguidos forem desistidos, o aviso automático é desligado para proteger a fila, e o painel avisa. Corrija o receptor e ligue de novo.
  • A fila guarda até 5.000 avisos por instância. Como a mesma mensagem pode chegar mais de uma vez, a deduplicação pelo uid não é opcional.

Problemas comuns

Sintoma Causa provável
"Endereço aponta para uma rede interna" O nome resolve para IP privado; use um endereço público
"Certificado https inválido" Certificado vencido ou cadeia incompleta no seu servidor
"Sem resposta em 10 s" O seu sistema demora; responda 2xx e processe depois
"Respondeu 4xx" A rota do seu sistema recusou; confira a assinatura e o caminho
Assinatura nunca confere Está calculando sobre o JSON já decodificado, ou o segredo está errado

Veja também o guia de primeiros passos, o de n8n e o de segurança.

Veja também

Índice completo: todos os guias. Sobre o produto: visão geral da API de WhatsApp da ProxyBox.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026; campos conferidos no código do receptor de avisos, contra a versão 1.2 da API.

Perguntas frequentes

O endereço pode ser http?
Não. Só https, na porta 443 (ou 8443), com endereço público. Endereços internos e o localhost são recusados.
Quanto tempo tenho para responder?
Até 10 segundos. Responda 2xx logo e processe depois. Qualquer outra resposta conta como falha.
Como evito processar o mesmo aviso duas vezes?
Guarde o campo uid de cada aviso. Se o mesmo uid chegar de novo, ignore.
Por quanto tempo fica o histórico?
Sete dias, com o código de resposta e o motivo de cada falha.
O aviso traz o arquivo da imagem ou do áudio?
Não. Traz o tipo, o nome e o tamanho. O arquivo se baixa pela rota de mídia recebida, de preferência na hora em que o aviso chega.

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