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

# Paginação, rate limit e limites

> Como paginar listas, o que acontece ao passar do limite de requisições e os tetos de fila e mídia.

## Paginação

Listas (`GET /chats`, `GET /contacts`, `GET /queue`…) aceitam `?page=` e `?page_size=` e respondem no mesmo envelope:

```json theme={"system"}
{ "data": [], "page": 1, "page_size": 100, "total": 342 }
```

| Parâmetro   | Padrão               | Máximo                |
| ----------- | -------------------- | --------------------- |
| `page`      | 1                    | —                     |
| `page_size` | 100 (20 em `/queue`) | 500 (100 em `/queue`) |

`GET /business/products` usa cursor (`next_cursor`) em vez de página, porque é o que o WhatsApp devolve.

## Rate limit

Cada instância tem um **token bucket**: 60 requisições por segundo sustentadas, com rajadas de até 120. Toda resposta informa o estado:

| Header                  | Significado                       |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Taxa sustentada (req/s)           |
| `X-RateLimit-Remaining` | Tokens restantes no bucket        |
| `Retry-After`           | Só no `429`: segundos até liberar |

Ao estourar, a resposta é `429` com `{ "error": { "code": "rate_limited" } }`. O limite conta **requisições HTTP**, não mensagens: uma chamada de `send-text` vale uma requisição mesmo que a mensagem fique um minuto na fila.

<Tip>
  O gargalo real de envio não é o rate limit da API, é o **intervalo anti-ban** da fila (1 a 3 s entre mensagens por padrão). Ver [Boas práticas](/guides/best-practices).
</Tip>

## Limites

| O quê                                                                      | Limite                                                     |
| -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Mensagens aguardando na fila, por instância                                | 1.000 (`409 queue_full`)                                   |
| Body da requisição                                                         | 64 MB (para mídia em base64)                               |
| Imagem, áudio, vídeo, sticker                                              | 16 MB                                                      |
| Documento                                                                  | 100 MB                                                     |
| Texto                                                                      | 65.536 caracteres                                          |
| Menções em uma mensagem                                                    | 500                                                        |
| Números em `phone-exists-batch`                                            | 50                                                         |
| Intervalo entre mensagens (`delay_message`) e "digitando" (`delay_typing`) | 0 a 15 s                                                   |
| Validade da URL de mídia recebida                                          | 24 horas                                                   |
| Tentativas de webhook                                                      | 5 (10 s, 1 min, 10 min, 1 h, 6 h) com timeout de 10 s cada |

## Idempotência

A API não tem chave de idempotência. Repetir um `POST /send-*` envia duas mensagens. Se a chamada falhou por rede **antes** de você ler a resposta, confira `GET /queue` (a mensagem ainda pode estar lá) ou espere o webhook `delivery` antes de tentar de novo. Do lado dos webhooks, use `event_id` para descartar entregas repetidas.