Recurso em beta: pode mudar. Provado em aparelho real em 14/11/2026, pela API: um envio com
X-Approval: requiredficou pendente (HTTP 202), a mensagem só chegou ao destinatário depois de aprovada, e uma segunda, rejeitada, nunca chegou. A aprovação pelo painel, o modobotse o modoallseguem em beta.
Atualização de 12/11/2026 (provado em aparelho real): a aprovação foi provada pela API pública:
202com mensagem pendente, aprovar envia e rejeitar descarta.
Por que usar?
Porque IA erra, e erra com confiança. Um bot de atendimento que responde sozinho em nome do seu número pode inventar um prazo, um preço ou uma promessa. Com a aprovação, uma pessoa vê o que ia ser enviado, aprova ou recusa, e só então a mensagem sai. É a rede de proteção natural para o conector MCP e para os bots enquanto você aprende a confiar neles.
Quais são os modos?
approval_mode |
O que segura |
|---|---|
off (padrão) |
Nada: tudo sai direto |
bots |
O que vier de um bot ou do conector MCP |
all |
Todo send.* e status.* feito pela API |
Além do modo da instância, qualquer chamada pode pedir aprovação só para ela, com "approval": true no corpo ou o cabeçalho X-Approval: required.
O que nunca espera aprovação: o que uma pessoa envia pelo painel; a mensagem que sai porque alguém aprovou; e o envio agendado que nasceu de uma aprovação (o agendamento só nasce depois dela).
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"approval_mode": "bots", "approval_ttl_hours": 24}'
approval_ttl_hours vai de 1 a 72 (padrão 24). Os dois ajustes só aparecem em GET /instance/settings depois de gravados.
O que a API responde ao envio?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE" -H "X-Approval: required" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Seu pedido saiu hoje."}'
{ "ok": true, "approval_id": 41, "status": "pending", "expires_at": "2026-11-13T10:00:00-03:00" }
HTTP 202. Mídia em pedido com aprovação só vale por url: base64 devolve 422 approval_media_url_only.
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 vejo e decido?
# lista (resumo; nunca traz o texto nem o número inteiro)
curl "https://proxybox.com.br/api/whatsapp/v1/approvals?status=pending&limit=20" -H "apikey: SUA_CHAVE"
# detalhe de uma
curl "https://proxybox.com.br/api/whatsapp/v1/approvals/41" -H "apikey: SUA_CHAVE"
# aprovar ou rejeitar
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/41/approve" -H "apikey: SUA_CHAVE"
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/41/reject" -H "apikey: SUA_CHAVE"
A lista e o detalhe da API mostram só o resumo (id, op, via, requested_by, status, error, datas e os quatro últimos dígitos do destino em to_tail4), nunca o texto. O texto e a prévia da mídia aparecem na tela do painel, que é onde a pessoa decide com conhecimento. Quem chama com o cabeçalho X-ProxyBox-Client: mcp (o conector de IA) não pode aprovar nem rejeitar: recebe 403. A decisão é sempre de uma pessoa.
O que acontece ao aprovar?
A mensagem é executada na hora, como um envio normal, e passa por todas as regras daquele momento: ritmo, limite diário, lista de "não perturbe", trava de contato novo e estado da conexão. Resultados possíveis:
| Situação | O que acontece |
|---|---|
| Deu certo | O status vira sent e a mensagem sai |
429, not_connected, new_contacts_locked ou serviço fora do ar |
Continua pendente, com error curto; tente aprovar de novo |
timeout (pode ter saído) |
Vira failed e nunca volta para a fila, para não enviar em dobro |
| Outro erro | Vira failed |
| Vencida | 410 ao aprovar |
Dois cliques ao mesmo tempo não enviam duas vezes: a reserva é atômica.
Quais são os tetos?
- até 100 pendentes por instância (acima disso,
422 approval_queue_full); - até 10 pendentes por contato (
422 approval_chat_full); - decididas com mais de 14 dias são apagadas.
Quais avisos chegam ao meu sistema?
Dois eventos novos, sem o texto da mensagem:
{
"event": "approval.requested",
"uid": "ap_41_req",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:00:01-03:00",
"occurred_at": null,
"data": { "approval_id": 41, "op": "send.text", "to_tail4": "9999", "via": "bot", "expires_at": "2026-11-13T10:00:00-03:00" }
}
approval.decided traz o resultado em status (sent, rejected, expired ou failed) e decided_by; approval.requested traz também requested_by. Além disso, passados 30 minutos com pendências, o dono recebe um e-mail por instância avisando que há mensagens esperando, também sem o conteúdo. A verificação de vencimento roda a cada 5 minutos.
Um fluxo com assistente de IA
- O dono liga
approval_mode: bots. - O assistente, pelo MCP, envia uma resposta. A API devolve
pending. - O dono recebe o aviso
approval.requested(ou o e-mail), abre o painel, lê o texto e aprova. - A mensagem sai e o evento
approval.decidedregistra a decisão.
Em Python, para aprovar tudo o que está pendente depois de uma checagem sua:
import os, requests
B = "https://proxybox.com.br/api/whatsapp/v1"
H = {"apikey": os.environ["WA_KEY"]}
for a in requests.get(f"{B}/approvals", headers=H, params={"status": "pending"}, timeout=30).json()["data"]:
# confira o conteúdo no painel antes de aprovar
requests.post(f"{B}/approvals/{a['id']}/approve", headers=H, timeout=30)
Só aprove em lote depois de ler cada texto. A graça do recurso é a leitura humana; automatizá-la desfaz a proteção.
Veja também
- Bots de WhatsApp pela API: tipos e limites
- MCP do WhatsApp para Claude e Cursor
- Equipe, papéis e métricas da API de WhatsApp
Índice completo: todos os guias. Sobre o produto: como funciona a API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Atualizado em 14/11/2026, contra as notas técnicas da aprovação humana da versão 1.2 e a prova em aparelho real. Recurso em beta.