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

# Webhook delivery

> O resultado de cada envio feito pela API: saiu do aparelho ou falhou, e por quê.

Todo `POST /send-*` responde `queued` na hora. O `delivery` é a segunda metade dessa história: chega quando o aparelho **efetivamente enviou** a mensagem (ou desistiu).

## Sucesso

```json theme={"system"}
{
  "type": "delivery",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968420000,
  "wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
  "message_id": "3EB0A9C6D2F1E4B5A7D0",
  "phone": "5511988887777"
}
```

## Falha

```json theme={"system"}
{
  "type": "delivery",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1Z",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968425000,
  "wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M02",
  "phone": "5511900000000",
  "error": "phone is not on WhatsApp",
  "error_code": "phone_not_on_whatsapp"
}
```

| Campo                 | Descrição                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `wabox_id`            | O mesmo devolvido pelo endpoint de envio. Use para casar com a chamada original                                                           |
| `message_id`          | Id da mensagem no WhatsApp (o mesmo da resposta do envio). Pode faltar em falhas                                                          |
| `phone`               | Destino                                                                                                                                   |
| `error`, `error_code` | Só em falha. `error_code` é estável; a lista está em [Erros](/api-reference/errors#erros-de-operacao-acoes-imediatas-ou-webhook-delivery) |

## Códigos mais comuns

| `error_code`            | O que fazer                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `phone_not_on_whatsapp` | Número sem WhatsApp. Confira antes com `GET /phone-exists/{phone}` ou `POST /phone-exists-batch`                                  |
| `media_download_failed` | O engine não conseguiu baixar a URL. Ela precisa ser pública e responder rápido; ou envie em base64                               |
| `media_invalid`         | Acima do limite (16 MB mídia / 100 MB documento) ou formato não aceito (ex.: sticker que não é WebP sem ffmpeg)                   |
| `message_not_found`     | Você respondeu/encaminhou/editou uma mensagem que o engine não tem em cache — veja [Fila e reenvio](/guides/queue-and-retries)    |
| `send_timeout`          | O aparelho não confirmou a tempo (celular sem rede por muito tempo). A mensagem **pode** ter saído; confira pelo `message_status` |
| `shadow_ban`            | O WhatsApp aceita mas não entrega. Pare os envios em massa e leia [Boas práticas](/guides/best-practices)                         |
| `not_allowed`           | Contato bloqueou o número, grupo só para admins, etc.                                                                             |

## O que `delivery` não é

* **Não** é recibo de entrega ao destinatário. `delivery` diz que a mensagem saiu do seu aparelho. "Chegou no celular do contato" é `message_status` com `RECEIVED`; "leu" é `READ`.
* **Não** vem para mensagens enviadas pelo celular — só para envios pela API.

## Fluxo completo de um envio

1. `POST /send-text` → `200 { wabox_id, message_id, status: "queued" }`
2. A mensagem espera o intervalo anti-ban na fila (1 a 3 s por padrão)
3. `delivery` com o mesmo `wabox_id`/`message_id` — ou `error_code`
4. `message_status` `SENT` → `RECEIVED` → `READ` (cada um quando o WhatsApp informar)