Recurso em beta: pode mudar. A lista de não perturbe e os ajustes de chamada são novos na versão 1.1.
Atualização de 12/11/2026 (provado em aparelho real): com o número na lista, o envio devolveu
409 opted_out; ao tirá-lo da lista, voltou a enviar. A recusa automática de chamadas não foi provada.
Resposta curta: a lista de não perturbe guarda os telefones que pediram para parar. Para qualquer envio a eles, a API responde 409 opted_out e não envia nada, sem gastar o seu ritmo. A recusa automática de chamadas liga com PUT /instance/settings e, se você quiser, responde uma vez por chamador a cada 6 horas.
Para que serve a lista de não perturbe?
Quem escreve "SAIR" ou "parar" e continua recebendo mensagem denuncia. Denúncia é o motivo que mais pesa contra um número. A lista é a forma de garantir, do lado da API, que um telefone que pediu para parar não receba mais nada daquela instância, mesmo que um fluxo seu esqueça de checar.
Ela é por instância: cada número tem a sua. Grupos não são afetados, porque o destino de um grupo não é um telefone. A lista compara as duas formas do nono dígito (veja número e identidade): incluir 5547999999999 também bloqueia 554799999999.
Como gerencio a lista pela API?
Todas as rotas usam a base https://proxybox.com.br/api/whatsapp/v1 e o cabeçalho apikey.
Ver a lista (paginada com limit, até 100, e offset):
curl "https://proxybox.com.br/api/whatsapp/v1/optout?limit=50&offset=0" -H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "total": 2, "optouts": [
{ "phone": "5547999999999", "reason": "pediu para parar", "created_at": "2026-11-11T10:02:11-03:00" },
{ "phone": "5511988887777", "reason": null, "created_at": "2026-11-11T11:15:40-03:00" }
] } }
Pôr um telefone (phone obrigatório, reason opcional, até 100 caracteres):
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/optout" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"phone":"5547999999999","reason":"pediu para parar"}'
{ "ok": true, "data": { "phone": "5547999999999", "reason": "pediu para parar", "already": false } }
Repetir o pedido não duplica: already vem verdadeiro e o reason é atualizado. A lista aceita até 20.000 telefones por instância; acima disso, 422 optout_limit.
Tirar um telefone, só quando a pessoa pedir para voltar:
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/optout/5547999999999" -H "apikey: SUA_CHAVE"
Se o telefone não está na lista, a resposta é 404 not_found. O painel tem a mesma lista, com botões de incluir e tirar.
O que acontece no envio?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Oi!"}'
{ "ok": false, "error": "opted_out", "message": "Este número está na lista \"não perturbe\" desta instância. Nada foi enviado. Para voltar a escrever, tire o número da lista." }
O 409 opted_out vale para todas as rotas de envio (texto, mídia, enquete e as demais) e para o envio agendado. Nada é enviado e o envio não conta no limite por minuto nem no diário.
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 ligar a pergunta "quer parar?" no seu fluxo?
A lista não lê as mensagens por você. O desenho recomendado é o do seu sistema reconhecer a palavra de saída no aviso message.received e chamar POST /optout. Um exemplo em Node.js:
// dentro do receptor do aviso, depois de conferir a assinatura
const { event, data } = JSON.parse(corpoBruto);
if (event === "message.received" && /^\s*(sair|parar|cancelar)\s*$/i.test(data.text) && data.from) {
await fetch("https://proxybox.com.br/api/whatsapp/v1/optout", {
method: "POST",
headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ phone: data.from, reason: "pediu para parar" }),
});
}
Se data.from vier nulo (o WhatsApp escondeu o telefone), registre a pessoa pelo seu lado e responda na própria conversa. Veja número e identidade.
Como recuso chamadas automaticamente?
O WhatsApp avisa a ProxyBox quando alguém liga, e o aviso call.received chega ao seu sistema. Se você quer que a instância recuse sozinha, use os ajustes:
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"reject_calls":true,"reject_calls_message":"Não atendemos ligações por aqui. Escreva a sua dúvida e respondemos em instantes."}'
{ "ok": true, "data": { "reject_calls": true, "reject_calls_message": "Não atendemos ligações por aqui. Escreva a sua dúvida e respondemos em instantes." } }
GET /instance/settings mostra o que está ligado. O que acontece quando uma chamada chega e reject_calls está ligado:
- A API recusa a chamada (
call.reject). - Se existe
reject_calls_message(até 200 caracteres), envia uma mensagem de texto a quem ligou, e no máximo uma a cada 6 horas por chamador. Essa mensagem passa pelo mesmo caminho dos outros envios: ritmo, pausa, trava de contato novo e lista de não perturbe valem. - O aviso
call.receivedcontinua indo para o seu sistema.
Chamadas de grupo não são recusadas automaticamente, e nada acontece se a instância estiver desconectada. Recusar manualmente continua possível com POST /calls/reject, passando from e call_id.
Na API de estilo Evolution, settings/set com rejectCall é aceito, mas não tem efeito: use os ajustes desta página.
Quais erros posso ver?
| HTTP | error |
Quando |
|---|---|---|
| 409 | opted_out |
Envio para telefone da lista |
| 404 | not_found |
Tirar da lista um telefone que não está nela |
| 422 | optout_limit |
Lista cheia (20.000) |
| 422 | invalid_request |
phone ausente ou inválido; veja fields |
As demais regras estão em erros e limites. Para uma visão do que protege o número, veja a restrição 463.
Veja também
- Erros e limites da API de WhatsApp
- Reagir, editar, apagar e status: API de WhatsApp
- 13 modelos para a API de WhatsApp (Woo, Asaas)
- Erro 463 do WhatsApp (contato novo): o que fazer
Índice completo: índice dos guias. Sobre o produto: a API de WhatsApp com IP de provedor.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Rotas conforme o adendo 8.2 e 8.3 da versão 1.1, revisadas em 11/11/2026.