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

# Autenticação

> instance_id e token na URL, e as camadas opcionais por cima.

A API pública autentica por **instância**. Não há OAuth nem chave de conta: cada instância tem um id e um token, e os dois vão na URL.

```text theme={"system"}
https://api.wabox.me/instances/{instance_id}/token/{token}/send-text
```

Os dois valores estão no painel, na aba **Dados da instância › Credenciais**, e também em `GET /me`.

## Camadas

| Camada                                                      | Escopo                           | Obrigatória?                    |
| ----------------------------------------------------------- | -------------------------------- | ------------------------------- |
| `instance_id` + `token` na URL                              | Instância                        | Sempre                          |
| Header [`Client-Token`](/security/client-token)             | Todas as instâncias do workspace | Quando ativada em **Segurança** |
| [Allowlist de IPs](/security/ip-allowlist)                  | Todas as instâncias do workspace | Quando preenchida               |
| [Assinatura HMAC](/security/webhook-signature) dos webhooks | Instância (sentido Wabox → você) | Verifique sempre                |

A ordem de verificação em cada requisição é: rate limit → token da instância → `Client-Token` → IP → assinatura ativa (`402` só em endpoints de envio).

## Boas práticas

* **Trate o token como senha.** Guarde em variáveis de ambiente ou cofre de segredos; nunca em código versionado, front-end ou logs de acesso (a URL inteira costuma ir para logs de proxies e CDNs — mascare-a).
* **Um token por integração** não é possível hoje (é um por instância). Se vários sistemas usam a mesma instância e um deles vazar, [gere um novo token](/security/credential-rotation) e atualize todos.
* **Ative o `Client-Token`** se a URL da API puder aparecer em lugares que você não controla (planilhas, ferramentas no-code compartilhadas).
* **Use a allowlist** quando os envios saem de IPs fixos (servidores próprios, NAT gateway).

## Erros de autenticação

| HTTP | `code`                  | Causa                                                                 |
| ---- | ----------------------- | --------------------------------------------------------------------- |
| 401  | `unauthorized`          | URL sem `instance_id` ou `token`                                      |
| 401  | `instance_not_found`    | Instância inexistente ou token errado (o Wabox não diz qual dos dois) |
| 401  | `client_token_required` | Header `Client-Token` ausente ou inválido                             |
| 403  | `ip_not_allowed`        | IP de origem fora da allowlist                                        |
| 402  | `subscription_required` | Teste vencido ou assinatura inativa (só envios)                       |