> ## 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. # Conceitos > Instância, fila, webhooks e os identificadores que aparecem em toda a API. ## Instância Uma instância é **um número de WhatsApp conectado como aparelho vinculado** (o mesmo mecanismo do WhatsApp Web). Ela tem um `instance_id`, um `token` e um ciclo de vida: | `status` | Significado | | -------------- | -------------------------------------------------------------------- | | `created` | Criada, sessão ainda não iniciada | | `starting` | Carregando a sessão | | `qr` | Aguardando leitura do QR code ou código de pareamento | | `connecting` | Sessão existe, (re)conectando | | `connected` | Pronta para enviar e receber | | `disconnected` | Queda temporária (rede, outra sessão web assumiu); reconecta sozinha | | `logged_out` | Aparelho removido no celular; precisa de novo QR | | `banned` | Número banido pelo WhatsApp | | `stopped` | Parada pela API ou por assinatura vencida | O celular **não precisa ficar online** o tempo todo: a sessão é multi-dispositivo. Ele precisa, porém, abrir o WhatsApp de vez em quando (o WhatsApp desconecta aparelhos vinculados após \~14 dias sem o celular). ## Envio assíncrono e fila Todo `POST /send-*` responde na hora com `{ id, message_id, wabox_id, status: "queued" }` e coloca a mensagem na **fila da instância**. A fila: * aplica um intervalo aleatório entre mensagens (1 a 3 s por padrão) — o principal mecanismo anti-ban; * segura as mensagens enquanto a instância está desconectada e as envia ao reconectar (desligável com `disable_enqueue_when_disconnected`); o que espera mais que `queue_max_age_hours` (padrão 12 h) é descartado com `delivery` `queue_expired`; * comporta até 1.000 mensagens por instância (`429 queue_full` acima disso). O resultado de cada envio chega no webhook **`delivery`**, e os recibos (entregue, lida) no **`message_status`**. Detalhes em [Fila e reenvio](/guides/queue-and-retries). Algumas ações não passam pela fila porque só fazem sentido agora: `read-message`, `send-presence` e tudo que é consulta ou administração (contatos, grupos, perfil…). Elas exigem instância conectada e respondem `409 instance_not_connected` caso contrário. ## Webhooks O Wabox faz `POST` na URL que você configurar, um tipo de evento por URL: | Tipo | Quando | | ---------------------------- | --------------------------------------------------------------------------------- | | `received` | Chegou uma mensagem (ou você enviou uma pelo celular/API, se `notify_sent_by_me`) | | `delivery` | Resultado de um envio feito pela API | | `message_status` | Recibo de mensagem sua: `SENT`, `RECEIVED`, `READ`, `PLAYED` | | `connected` / `disconnected` | Estado da conexão mudou | | `chat_presence` | Contato digitando, gravando, online | Cada entrega vem assinada (`X-Wabox-Signature`), tem `event_id` único e é reenviada se você não responder 2xx. Veja [Visão geral dos webhooks](/webhooks/overview). ## Identificadores Só dígitos, com DDI e DDD: `5511988887777`. O mesmo campo aceita outros tipos de chat: | Valor | Chat | | ------------------------------- | ----------------------------------------------------------- | | `5511988887777` | Conversa individual | | `120363012345678901-group` | Grupo (o JID cru `120363012345678901@g.us` também é aceito) | | `120363012345678901@newsletter` | Canal | | `98765432109876@lid` | Contato identificado por LID (veja abaixo) | | `status@broadcast` | Seu status (stories) | Ids de mensagem do WhatsApp são gerados pelo remetente. O Wabox gera o id no momento em que aceita o envio, devolve na resposta e manda o aparelho usar exatamente esse id. Por isso o `message_id` da resposta é o mesmo que aparece depois em `delivery`, `message_status` e nas respostas do contato (`reference_message_id`). `id` na resposta é um alias de `message_id` (facilita mapear em ferramentas no-code). Id da mensagem **na fila do Wabox** (`wbx_...`). Use para remover uma mensagem da fila (`DELETE /queue/{wabox_id}`) e para casar o webhook `delivery` com a chamada original. ULID único por evento. Entregas podem repetir (reenvio após timeout, por exemplo); guarde os `event_id` já processados. O WhatsApp está migrando para **LIDs** (`123456789012345@lid`), identificadores que não expõem o número. Em alguns chats (especialmente grupos e contatos que ativaram o número oculto) você pode receber `chat_lid`/`sender_lid`/`participant_lid` e, em casos raros, um `phone` no formato `xxx@lid` sem o número real. Guarde o LID junto com o número: os endpoints aceitam `xxx@lid` em `phone`. Mais em [Identificadores](/guides/identifiers). ## Workspace, instâncias e segurança Uma conta (workspace) pode ter várias instâncias e vários usuários. Duas proteções valem para **todas** as instâncias do workspace: o header [`Client-Token`](/security/client-token) e a [allowlist de IPs](/security/ip-allowlist).