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

# Fila e reenvio

> Como a fila de saída funciona, o que acontece quando a instância cai e como inspecionar ou limpar mensagens pendentes.

Cada instância tem uma fila de saída. Todo `POST /send-*` (e reações, encaminhamentos, enquetes, fixar, apagar) entra nela e sai na ordem, respeitando o intervalo anti-ban.

## Ciclo de uma mensagem

```text theme={"system"}
POST /send-text ──► fila (status "queued") ──► intervalo 1–3 s ──► aparelho envia ──► webhook delivery
                                                                                  └─► message_status SENT → RECEIVED → READ
```

* **Resposta imediata** com `wabox_id` (id na fila) e `message_id` (id no WhatsApp, já definitivo).
* **Intervalo**: aleatório entre `delay_message_min_ms` e `delay_message_max_ms` (padrão 1.000 a 3.000 ms), contado do fim da mensagem anterior. `delay_message` na chamada substitui esse intervalo para aquela mensagem; `delay_typing` acrescenta "digitando…" antes.
* **Mídia**: um envio de mídia por vez por instância; textos não esperam mídia.

## Quando a instância está desconectada

Por padrão, a fila **aceita e segura** as mensagens. Ao reconectar (`connected`), elas saem na ordem, com o intervalo normal — nada é disparado de uma vez.

Se preferir falhar rápido, ligue `disable_enqueue_when_disconnected` em `PUT /settings`: os envios passam a responder `409 queue_disabled_while_disconnected` enquanto o número estiver fora.

<Warning>
  Mensagens presas na fila por muito tempo podem ficar obsoletas ("seu código expira em 5 minutos"). Para conteúdo sensível a tempo, verifique `GET /status` antes de enviar ou use `disable_enqueue_when_disconnected` e trate o 409.
</Warning>

## Inspecionar e limpar

```bash theme={"system"}
# O que está esperando
curl https://api.wabox.me/instances/{instance_id}/token/{token}/queue?page=1&page_size=50

# Remover uma mensagem específica
curl -X DELETE https://api.wabox.me/instances/{instance_id}/token/{token}/queue/wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01

# Esvaziar a fila
curl -X DELETE https://api.wabox.me/instances/{instance_id}/token/{token}/queue
```

`GET /queue` lista `wabox_id`, `message_id`, `phone`, `type` e o conteúdo, paginado. Mensagens já enviadas não aparecem (o Wabox não guarda histórico).

## Capacidade

A fila comporta **1.000 mensagens** por instância. Acima disso, `POST /send-*` responde `409 queue_full`. Na prática, com o intervalo padrão, 1.000 mensagens levam cerca de 30 a 50 minutos para sair — se você está batendo nesse teto, distribua entre várias instâncias.

## Reenvio e falhas

* O Wabox tenta enviar cada mensagem enquanto o aparelho estiver conectado; falhas definitivas (`phone_not_on_whatsapp`, `media_invalid`, `message_not_found`, `not_allowed`) viram `delivery` com `error_code` e a mensagem sai da fila.
* `send_timeout` significa que o aparelho não confirmou a tempo. A mensagem **pode** ter saído. Não reenvie às cegas: espere o `message_status` ou confira com o contato.
* Não existe reenvio automático pela API. Se você precisa garantir entrega, implemente no seu lado: registre `wabox_id`, espere `delivery`, e reenvie só em falhas definitivas que façam sentido repetir.

## Mensagens referenciadas (responder, encaminhar, editar, votar)

`reply_to_message_id`, `forward-message`, `edit_message_id`, `send-poll-vote` e `send-event-response` precisam do **conteúdo** da mensagem original, que o WhatsApp não fornece sob demanda. O engine mantém um cache em memória (as últimas \~4.000 mensagens por instância, recebidas ou enviadas desde o último restart). Fora do cache, o resultado é `delivery` com `message_not_found`.

Na prática: responder/encaminhar mensagens recentes funciona; mensagens de dias atrás ou anteriores a um restart do engine falham com `message_not_found`. Se a citação for opcional para você, trate esse erro reenviando sem `reply_to_message_id`.

## Ordem entre instâncias

Filas são independentes por instância. Se você tem várias instâncias enviando para o mesmo contato, não há ordenação entre elas.