> ## 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. # 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. ### Validade das mensagens na fila Uma mensagem que espera mais que **`queue_max_age_hours`** (padrão **12 h**, de 1 a 168) sai da fila **sem ser enviada** e você recebe um `delivery` com `error_code: "queue_expired"` — mesmo com a instância ainda desconectada. Ao reconectar, só o que ainda está dentro da validade é enviado. ```bash theme={"system"} curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/settings \ -H "Content-Type: application/json" \ -d '{ "queue_max_age_hours": 2 }' ``` Também dá para ajustar no painel, em **Webhooks e configurações › Geral**. Mensagens presas na fila por muito tempo podem ficar obsoletas ("seu código expira em 5 minutos"). Para conteúdo sensível a tempo, use uma validade curta (`queue_max_age_hours: 1`), verifique `GET /status` antes de enviar ou ligue `disable_enqueue_when_disconnected` e trate o 409. ## 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 o que já saiu; o [histórico recente](/api-reference/chats/chats-phone-messages) vem só do pareamento). ## Capacidade A fila comporta **1.000 mensagens** por instância. Acima disso, `POST /send-*` responde `429 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. * `queue_expired` significa que a mensagem passou de `queue_max_age_hours` esperando na fila e foi descartada sem envio. Reenviar é seguro (nada saiu). * Falhas **transitórias** entre a fila e o aparelho (engine reiniciando, instância caindo bem na hora) não viram `delivery`: a mensagem volta para a fila e é tentada de novo automaticamente (30 s, 1 min, 2 min… até 10 min entre tentativas, ou no próximo `connected`). Uma rotina a cada minuto ainda recupera mensagens que ficaram presas "enviando" sem resposta (até 3 tentativas, depois `delivery` com `send_failed`). * Fora isso, não existe reenvio automático de falhas definitivas. Se você precisa garantir entrega, implemente no seu lado: registre `wabox_id`, espere `delivery`, e reenvie só em falhas 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.