> ## 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 > Cada mudança de conexão da instância: aguardando QR code, conectou, caiu, deslogou ou foi banida. 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](https://developer.wabox.me/guides/queue-and-retries.md) começa a drenar o que acumulou | Libere o canal | | `disconnected` | Queda temporária, reconecta sozinho. Exceção: `disconnect_reason: qr_timeout` (o QR expirou sem ser lido) | Nada. Não chame `POST /restart`. Com `qr_timeout`, chame `GET /qr-code` quando o cliente quiser conectar | | `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](https://developer.wabox.me/guides/best-practices.md) | | `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 | | `qr_timeout` | `disconnected` | Ninguém leu o QR code em \~13 minutos e o pareamento parou (a instância não fica gerando QR indefinidamente) | Só quando o cliente for conectar: `GET /qr-code` recomeça o pareamento com um QR novo | | `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 o Wabox nunca o envia. `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` e depois `connected`. O Wabox gera QR codes por cerca de 13 minutos. Se ninguém ler nesse tempo, o pareamento para. Chega `disconnected` com `disconnect_reason: qr_timeout` e nenhum QR novo é gerado. Para tentar de novo, chame `GET /qr-code` (ou `GET /qr-code/image`, ou o código de telefone). O pareamento recomeça do zero, com mais \~13 minutos. ## Configuração Configure com `instance_status_url` em `PUT /webhooks` (ou `PUT /webhooks/instance_status` com `{ "value": "https://..." }`), com `PUT /account/webhooks` para o workspace inteiro, ou no campo **Ao mudar o status da instância** do painel. No modo de URL única ele já chega em `single_url`. Para silenciar sem apagar a URL, use `ignore_instance_status_callback: true`. ## Recomendações * Trate `logged_out` e `banned` como alertas e 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 um `POST /restart` automático, porque a reconexão já está em curso e reiniciar só atrasa. Com `qr_timeout` também não. Gere o QR de novo só quando alguém for ler. * 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. > [!NOTE] > > `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. O Wabox migrou automaticamente para `instance_status_url` quem tinha uma dessas URLs configurada. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.