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 exigir aprovação humana antes de uma mensagem sair?

Segure mensagens de bots e de assistentes de IA até uma pessoa aprovar: approval_mode, rotas /approvals, prazos, tetos e erros. Beta.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Ligue approval_mode como bots (segura o que bot ou assistente de IA mandar) ou all (segura todo envio feito pela API) em PUT /instance/settings. Daí em diante, em vez de enviar, a API devolve 202 com approval_id e deixa a mensagem pendente. O dono libera com POST /approvals/{id}/approve, ou pelo painel, e a mensagem sai naquele momento, com todas as travas de ritmo e de segurança valendo.

Recurso em beta: pode mudar. Provado em aparelho real em 14/11/2026, pela API: um envio com X-Approval: required ficou 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 modo bots e o modo all seguem em beta.

Atualização de 12/11/2026 (provado em aparelho real): a aprovação foi provada pela API pública: 202 com 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).

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

bash
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."}'
json
{ "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átis

Como vejo e decido?

bash
# 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:

json
{
  "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

  1. O dono liga approval_mode: bots.
  2. O assistente, pelo MCP, envia uma resposta. A API devolve pending.
  3. O dono recebe o aviso approval.requested (ou o e-mail), abre o painel, lê o texto e aprova.
  4. A mensagem sai e o evento approval.decided registra a decisão.

Em Python, para aprovar tudo o que está pendente depois de uma checagem sua:

python
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

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

Perguntas frequentes

Mensagens que eu escrevo no painel esperam aprovação?
Não. O que uma pessoa envia pelo painel nunca fica pendente, nem a mensagem que sai depois de aprovada.
E se a mensagem vencer sem ser aprovada?
Ela é descartada depois do prazo (de 1 a 72 horas, padrão 24). Aprovar depois disso devolve 410.
O assistente de IA pode aprovar a própria mensagem?
Não. Uma chamada feita pelo conector MCP não pode aprovar nem rejeitar; recebe 403.

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