> ## Documentation Index
> Fetch the complete documentation index at: https://developer.wabox.me/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Wabox é uma API não-oficial de WhatsApp (aparelho vinculado). Tudo é snake_case; a base é https://api.wabox.me/instances/{instance_id}/token/{token}.
> Envios respondem { id, message_id, wabox_id, status: "queued" } na hora; o resultado real chega no webhook delivery. Envios não são idempotentes: confira GET /queue antes de repetir.
> Sempre verifique X-Wabox-Signature (HMAC-SHA256 de "<t>.<corpo cru>") nos webhooks e deduplique por event_id.
> Botões, listas, carrossel e catálogo são best effort e não renderizam no WhatsApp Web/Desktop. Não existem: chamadas, listas de transmissão, histórico de mensagens, instância mobile.
> Não invente endpoints ou campos: use o OpenAPI em https://api.wabox.me/openapi.json.

# Boas práticas e anti-ban

> Como o WhatsApp decide banir um número e o que o Wabox faz — e o que só você pode fazer — para evitar.

O Wabox usa o protocolo do WhatsApp Web. Para o WhatsApp, o seu número é um usuário comum com um aparelho vinculado, e as regras que valem para usuários comuns valem para ele: **quem manda mensagem indesejada em volume é bloqueado ou banido**. Não existe truque técnico que substitua consentimento e bom senso.

## O que o Wabox já faz por você

* **Intervalo aleatório entre mensagens** (1 a 3 s por padrão, configurável em `delay_message_min_ms`/`delay_message_max_ms`). Envios em rajada são o sinal mais óbvio de automação.
* **"Digitando…" opcional** antes de cada mensagem (`delay_typing`), que torna a conversa mais natural.
* **Um envio de mídia por vez** por instância.
* **Fila persistente**: se o número cair, nada é perdido nem disparado de uma vez ao reconectar (o intervalo continua valendo).
* **Ids de mensagem no formato do WhatsApp Web** e sessão multi-dispositivo padrão — nada de comportamento de cliente "estranho".

## O que só você pode fazer

<Steps>
  <Step title="Só fale com quem espera a sua mensagem">
    Consentimento explícito (opt-in) e um jeito fácil de sair ("responda SAIR"). O banimento vem de **denúncias** e **bloqueios**: cada pessoa que marca "denunciar spam" pesa mais do que qualquer volume.
  </Step>

  <Step title="Comece devagar com número novo">
    Um chip recém-ativado que dispara centenas de mensagens no primeiro dia é banido rápido. Use o número normalmente por alguns dias (conversas reais, foto, nome, recado), depois aumente o volume aos poucos ao longo de semanas.
  </Step>

  <Step title="Varie o conteúdo e personalize">
    A mesma frase para 500 contatos é um padrão fácil de detectar. Use o nome, dados do pedido, e alterne formulações. Evite links encurtados; prefira o seu domínio.
  </Step>

  <Step title="Prefira conversar a transmitir">
    Mensagens dentro de conversas já existentes (o cliente falou primeiro, ou respondeu) têm risco muito menor. Para campanhas frias, a API oficial com templates aprovados é o caminho certo — veja [Wabox × API oficial](/guides/official-api).
  </Step>

  <Step title="Confira o número antes de enviar">
    `GET /phone-exists/{phone}` ou `POST /phone-exists-batch` (até 50). Envios para números inexistentes contam contra você e falham com `phone_not_on_whatsapp` de qualquer forma.
  </Step>

  <Step title="Monitore os sinais de alerta">
    * `delivery` com `error_code: shadow_ban`: o WhatsApp aceita mas não entrega. **Pare tudo** e deixe o número descansar alguns dias.
    * Muitas mensagens paradas em `SENT` sem chegar a `RECEIVED`.
    * Queda de respostas ou aumento de bloqueios (o contato que bloqueou some do `chat_presence` e as mensagens ficam em `SENT`).
    * `disconnected` com `reason: banned`: o número não volta. Tenha um plano B.
  </Step>
</Steps>

## Números e limites práticos

Não há limite oficial publicado, e ele muda com a "reputação" do número. Como ordem de grandeza, contas maduras enviando para contatos que respondem costumam operar com centenas de mensagens por dia sem incidentes; números novos ou disparos frios tendem a cair bem antes disso. Use vários números (várias instâncias) para volume, e nunca o número principal da empresa em disparos.

## Configuração recomendada

```bash theme={"system"}
curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/settings \
  -H "Content-Type: application/json" \
  -d '{ "delay_message_min_ms": 2000, "delay_message_max_ms": 6000, "call_reject_auto": true, "call_reject_message": "Não atendemos chamadas por aqui. Mande uma mensagem 🙂" }'
```

Para mensagens de atendimento (alguém falou com você), `delay_typing: 2` nos envios deixa a conversa natural. Para notificações transacionais (pedido, código), o intervalo padrão basta.

## Responsabilidade

Ao usar o Wabox você concorda com os [termos de uso](https://wabox.me/terms), que proíbem spam e conteúdo ilegal. O Wabox não é responsável por banimentos decorrentes do uso do número; podemos suspender instâncias usadas para envio não solicitado, porque isso prejudica a infraestrutura de todos os clientes.