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

# Mídia

> URL ou base64, limites, formatos, conversões automáticas e a expiração das mídias recebidas.

## Enviando

O campo de mídia (`image`, `audio`, `video`, `ptv`, `gif`, `document`, `sticker`) aceita três formas:

<Tabs>
  <Tab title="URL pública">
    ```json theme={"system"}
    { "phone": "5511988887777", "image": "https://cdn.loja.com/produto.jpg", "caption": "Pronto para envio" }
    ```

    O engine baixa a URL na hora do envio. Ela precisa ser acessível da internet, sem autenticação, e responder em poucos segundos. URLs temporárias (assinadas) funcionam desde que ainda estejam válidas quando a mensagem sair da fila.
  </Tab>

  <Tab title="data: URL">
    ```json theme={"system"}
    { "phone": "5511988887777", "image": "data:image/png;base64,iVBORw0KGgo..." }
    ```

    O `mime_type` vem embutido.
  </Tab>

  <Tab title="base64 puro">
    ```json theme={"system"}
    { "phone": "5511988887777", "document": "JVBERi0xLjQK...", "mime_type": "application/pdf", "file_name": "contrato.pdf" }
    ```

    Informe `mime_type` e `file_name` quando o tipo não puder ser inferido.
  </Tab>
</Tabs>

O Wabox **não armazena** a mídia enviada: ela passa pelo payload, é cifrada e sobe para os servidores do WhatsApp, e o corpo é descartado.

## Limites

|                                    | Limite                                                   |
| ---------------------------------- | -------------------------------------------------------- |
| Imagem, áudio, vídeo, sticker, GIF | 16 MB                                                    |
| Documento                          | 100 MB                                                   |
| Body da requisição (para base64)   | 64 MB — acima disso, use URL                             |
| Envios de mídia simultâneos        | 1 por instância (mídia é mais lenta; textos não esperam) |

Estourar o limite resulta em `delivery` com `error_code: media_invalid`. URL inacessível resulta em `media_download_failed`.

## Formatos e conversões

Os servidores do Wabox têm ffmpeg, então a maioria das conversões é automática:

| Tipo                                  | Você envia                    | O contato recebe                                                    |
| ------------------------------------- | ----------------------------- | ------------------------------------------------------------------- |
| `send-audio` com `ptt: true` (padrão) | mp3, wav, m4a, ogg…           | Voice note em Opus/OGG com forma de onda (toca em iOS e Android)    |
| `send-audio` com `ptt: false`         | qualquer áudio                | Arquivo de áudio como enviado                                       |
| `send-sticker`                        | png, jpg, webp, gif           | WebP 512×512 (animado se a origem for animada)                      |
| `send-gif`                            | gif ou mp4                    | mp4 com reprodução em loop (é assim que o WhatsApp representa GIFs) |
| `send-video`                          | mp4 (H.264 + AAC) recomendado | Como enviado, com thumbnail gerada                                  |
| `send-ptv`                            | vídeo quadrado, curto         | Vídeo redondo ("video note")                                        |
| `send-image`                          | jpg, png, webp                | JPEG com thumbnail                                                  |
| `send-document`                       | qualquer arquivo              | Como enviado; PDFs ganham prévia da primeira página                 |

<Note>
  Se um servidor específico estiver sem ffmpeg, o envio ainda funciona: áudio vai como está (pode não tocar no iOS se não for Opus), sticker exige WebP e GIF exige mp4.
</Note>

## Recebendo

Mídias recebidas chegam no webhook `received` já **decifradas**, como URL assinada:

```json theme={"system"}
"image": {
  "mime_type": "image/jpeg",
  "url": "https://media.wabox.me/8f2a3c1e/2026/09/03/3EB0A9C6D2F1E4B5A7C9.jpg?X-Amz-Signature=...",
  "thumbnail_url": "https://media.wabox.me/.../3EB0A9C6D2F1E4B5A7C9.thumb.jpg?X-Amz-Signature=...",
  "file_size": 245678,
  "sha256": "9f86d081..."
}
```

* A URL **expira em 24 horas**. Baixe e guarde no seu storage se precisar depois; o Wabox não é um repositório.
* Se a decifração ou o download falhar, `url` vem ausente e `download_error` diz o motivo. Peça para o contato reenviar.
* `view_once: true`: mídia de visualização única. O WhatsApp espera que ela não seja reencaminhada; trate como sensível.
* `sha256` permite deduplicar arquivos que chegam mais de uma vez.

## Privacidade

Conteúdo de mensagens não fica em repouso no Wabox: o único lugar onde mídia recebida existe é o storage temporário das URLs assinadas, com expiração. Mensagens de texto não são armazenadas em lugar nenhum além da fila de saída (até serem enviadas).