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

# Webhooks connected e disconnected

> Saiba na hora quando o número conecta, cai, é deslogado ou banido — e o que fazer em cada caso.

## connected

```json theme={"system"}
{
  "type": "connected",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1W",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968030000,
  "connected": true,
  "phone": "5511999998888"
}
```

Dispara quando o número lê o QR code / código de pareamento e quando a sessão reconecta depois de uma queda. `phone` é o número conectado — use para confirmar que a instância está ligada ao número certo.

Ao conectar, a [fila](/guides/queue-and-retries) começa a drenar o que acumulou enquanto a instância estava fora.

## disconnected

```json theme={"system"}
{
  "type": "disconnected",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786971600000,
  "disconnected": true,
  "reason": "logged_out",
  "error": "Device has been disconnected"
}
```

| `reason`          | O que aconteceu                                                                     | Precisa de ação?                                                                               |
| ----------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `network`         | Rede caiu entre o Wabox e o WhatsApp, ou o celular ficou muito tempo offline        | Não — reconecta sozinho; `connected` avisa quando voltar                                       |
| `stream_replaced` | Outra sessão do WhatsApp Web com o mesmo aparelho vinculado assumiu                 | Não — reconecta sozinho. Se repete, alguém está usando as credenciais da sessão em outro lugar |
| `logged_out`      | O aparelho foi removido em **Aparelhos conectados** no celular, ou a sessão expirou | **Sim**: ler o QR de novo (`GET /qr-code`)                                                     |
| `banned`          | O WhatsApp baniu o número                                                           | **Sim**: o número não volta; leia [Boas práticas](/guides/best-practices)                      |
| `stopped`         | A instância foi parada pela API/painel ou por assinatura vencida                    | Depende: `POST /restart` ou regularizar a assinatura                                           |
| `engine_shutdown` | Manutenção do lado do Wabox                                                         | Não — reconecta ao voltar                                                                      |
| `unknown`         | Queda sem motivo identificado                                                       | Aguarde; se não voltar, `POST /restart`                                                        |

`error` é a mensagem crua do protocolo, útil para suporte.

## Recomendações

* Trate `logged_out` e `banned` como alertas: avise quem opera o número (e-mail, Slack). Enquanto isso, os envios continuam entrando na fila, a menos que `disable_enqueue_when_disconnected` esteja ligado.
* Não reaja a `network`/`stream_replaced` com `POST /restart` automático: a reconexão já está em curso e reiniciar só atrasa.
* `GET /status` continua sendo a fonte de verdade para consultas pontuais; os webhooks evitam ficar consultando em loop.