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

Não perturbe e chamadas: lista de quem pediu para parar e recusa automática

Lista de não perturbe que bloqueia envios a quem pediu para parar e recusa automática de chamadas, com mensagem opcional. Rotas /optout e ajustes.

6 min de leitura Atualizado em 14 de novembro de 2026

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):

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

bash
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"}'
json
{ "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:

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

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

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

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:

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

  1. A API recusa a chamada (call.reject).
  2. 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.
  3. O aviso call.received continua 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

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

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