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

# Rotação de token e segredo

> O que fazer quando um token da instância, o Client-Token ou o segredo do webhook vaza.

Três segredos, três formas de trocar. Nenhum deles tem período de convivência exceto o segredo do webhook — planeje a troca com isso em mente.

| Segredo                           | Onde trocar                                             | Efeito                                                                |
| --------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
| **Token da instância**            | Painel › instância › Credenciais › **Gerar novo token** | O token anterior para de funcionar na hora, em todas as chamadas      |
| **Client-Token** (workspace)      | Painel › Segurança › **Gerar novo token**               | Idem, para todas as instâncias do workspace                           |
| **Segredo do webhook** (`whsec_`) | `POST /webhooks/secret` ou painel › Webhooks            | Entregas já na fila mantêm o segredo antigo até esgotar as tentativas |

## Roteiro para um token vazado

<Steps>
  <Step title="Gere o token novo">
    No painel, em **Credenciais** da instância, clique em **Gerar novo token** e confirme. A partir desse instante, requisições com o token antigo recebem `401 instance_not_found`.
  </Step>

  <Step title="Atualize as integrações">
    Troque o valor em todos os sistemas que usam a instância. Se você guarda a URL completa (com o token) em ferramentas no-code, é aqui que vai doer — prefira guardar `instance_id` e `token` separados.
  </Step>

  <Step title="Confira os logs de webhook e a fila">
    Um token vazado pode ter sido usado para enviar mensagens. Veja `GET /queue` (e limpe com `DELETE /queue` se houver envios estranhos) e os **Logs de webhook** no painel.
  </Step>

  <Step title="Feche a porta">
    Ative o [`Client-Token`](/security/client-token) e, se os envios saem de IPs fixos, a [allowlist](/security/ip-allowlist). Assim uma URL vazada sozinha não basta.
  </Step>
</Steps>

<Note>
  A rotação do token da instância **não** desconecta o número nem mexe na fila — a sessão do WhatsApp continua ativa.
</Note>

## Troca do segredo do webhook sem perder entregas

1. Chame `POST /webhooks/secret`; guarde o novo `secret`.
2. Faça o seu endpoint aceitar **os dois** segredos por algumas horas (o suficiente para a última tentativa de reenvio, que acontece 6 h depois da primeira falha).
3. Remova o antigo.

## Desconectar de vez

Se o número em si foi comprometido (celular perdido, por exemplo), use `POST /disconnect` para encerrar a sessão do WhatsApp. A instância volta para `qr` e nada pode ser enviado até uma nova leitura. No celular, confira **Aparelhos conectados** e remova sessões desconhecidas.