> ## 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 ".") 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. # Webhook instance_status > O webhook de conexão: aguardando QR code, conectou, caiu, foi deslogado ou banido — e o que fazer em cada caso. ```json theme={"system"} { "type": "instance_status", "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1Y", "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b", "momment": 1786971600000, "status": "logged_out", "previous_status": "connected", "disconnect_reason": "logged_out", "reason": "Device has been disconnected" } ``` Dispara **uma vez a cada mudança** de `status` da instância — o mesmo valor que `GET /status` devolve. É o único webhook de conexão: com ele você mostra a tela de QR code na hora certa, libera o canal quando o número entra e avisa quando ele cai, sem consultar a API em loop. | Campo | Descrição | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `status` | Status novo | | `previous_status` | Status anterior. Ausente na primeira transição de uma instância recém-criada | | `phone` | Número conectado. Vem quando `status` é `connected` — use para confirmar que a instância está ligada ao número certo | | `disconnect_reason` | O que derrubou a sessão (tabela abaixo). Vem quando a mudança foi causada por uma desconexão | | `reason` | Texto livre para log e suporte: a mensagem crua do protocolo numa queda, `logout requested`… Não tome decisões com base nele | ## Status | `status` | Significado | O que fazer | | -------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | `starting` | A sessão está sendo carregada | Nada | | `qr` | **Aguardando a leitura do QR code** (ou código de pareamento) | Mostre o QR ao cliente: `GET /qr-code` | | `connecting` | Sessão existente (re)conectando ao WhatsApp | Nada | | `connected` | Número conectado, pronto para enviar e receber. A [fila](/guides/queue-and-retries) começa a drenar o que acumulou | Libere o canal | | `disconnected` | Queda temporária — reconecta sozinho | Nada; **não** chame `POST /restart` | | `logged_out` | Aparelho removido no celular, sessão expirada ou logout pela API | **Peça um novo QR code** | | `banned` | O WhatsApp baniu o número | O número não volta; leia [Boas práticas](/guides/best-practices) | | `stopped` | Instância parada pela API/painel, exclusão ou assinatura | `POST /restart` ou regularize a assinatura | ## Motivo da desconexão | `disconnect_reason` | `status` | O que aconteceu | Precisa de ação? | | ------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `network` | `disconnected` | Rede caiu entre o Wabox e o WhatsApp, ou o celular ficou muito tempo offline | Não — reconecta sozinho; chega `connected` quando voltar | | `stream_replaced` | `disconnected` | 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 | | `engine_shutdown` | `disconnected` | Manutenção do lado do Wabox | Não — reconecta ao voltar | | `unknown` | `disconnected` | Queda sem motivo identificado | Aguarde; se não voltar, `POST /restart` | | `logged_out` | `logged_out` | O aparelho foi removido em **Aparelhos conectados** no celular, a sessão expirou ou houve logout pela API | **Sim**: ler o QR de novo (`GET /qr-code`) | | `banned` | `banned` | O WhatsApp baniu o número | **Sim**: o número não volta | | `stopped` | `stopped` | A instância foi parada pela API/painel ou por assinatura vencida | Depende: `POST /restart` ou regularizar a assinatura | ## O QR code não vem no webhook O código muda a cada poucos segundos, então ele nunca é enviado: `status: "qr"` é o sinal para o seu sistema começar a buscar `GET /qr-code` (e renovar enquanto o status for `qr`). Você recebe **um** `instance_status` quando a instância passa a aguardar o QR, não um por código gerado. Quando o cliente lê o código, chegam `connecting` → `connected`. ## Configuração `instance_status_url` em `PUT /webhooks` (ou `PUT /webhooks/instance_status` com `{ "value": "https://..." }`), `PUT /account/webhooks` para o workspace inteiro, ou o campo **Ao mudar o status da instância** no painel. No modo de URL única ele já chega em `single_url`. Para silenciar sem apagar a URL: `ignore_instance_status_callback: true`. ## 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 `disconnected` com `POST /restart` automático: a reconexão já está em curso e reiniciar só atrasa. * Eventos podem chegar fora de ordem numa retentativa: use `momment` para não deixar um `disconnected` antigo derrubar um canal que já voltou. * `GET /status` continua sendo a fonte de verdade para consultas pontuais; o webhook evita ficar consultando em loop. `instance_status` substituiu os antigos webhooks `connected` e `disconnected` (e os campos `connected_url` / `disconnected_url`). O que eles traziam está aqui: `phone` ao conectar, `disconnect_reason` + `reason` ao cair. Quem tinha uma dessas URLs configurada foi migrado automaticamente para `instance_status_url`.