Midia

Hub armazena midia em MinIO em 3 cenarios:

Inbound — quando recebe mensagem com anexo (message.received com type=image|audio|document|video|sticker)
Outbound URL — quando voce envia via POST /v1/messages com content.url, o hub baixa e persiste
Upload direto — voce mesmo faz POST /v1/media antes de enviar (Onda 3.6b)

Em todos os casos, media_id (ULID) identifica o arquivo. Use GET /v1/media/:id pra baixar.

`GET /v1/media/:id`

GET /v1/media/01HZTQMEDIA...
Authorization: Bearer APP_KEY

200 OK stream binario com Content-Type correto (image/jpeg, audio/ogg, etc) + headers de cache.

Quem pode baixar

App so consegue baixar midia de mensagem que ela tem acesso:

Outbound (a app mandou) — app_id da mensagem == app autenticada
Inbound (alguem mandou pro chip) — app precisa de can_receive=true em app_chip_access no chip da mensagem

Caso contrario: 404 media-not-found.

`POST /v1/media` — upload direto

Pra enviar midia sem precisar hospedar URL publica, faca upload primeiro e use o media_id retornado em POST /v1/messages.

POST /v1/media?filename=relatorio.pdf
Authorization: Bearer APP_KEY
Content-Type: application/pdf

<bytes binarios do arquivo>

Item	Notas
`Content-Type`	mimetype real (`image/jpeg`, `image/webp`, `audio/ogg`, `application/pdf`, etc). Nao use `application/octet-stream` — hub usa o mimetype pra inferir `kind`
`?filename=...`	so pra documentos (default null em image/audio/sticker)
Body	bytes raw, nao multipart/form-data
Tamanho maximo	`MEDIA_MAX_BYTES` (default 16MB)

Resposta 201:

{
  "id": "01HZTQUPLOAD...",
  "kind": "document",
  "mimetype": "application/pdf",
  "size": 524288,
  "filename": "relatorio.pdf",
  "created_at": "2026-05-03T20:00:00.000Z"
}

Inferencia de `kind`

Mimetype	Kind
`image/webp`	`sticker`
`image/*`	`image`
`audio/*`	`audio`
`video/*`	`video`
qualquer outro	`document`

Usando o `media_id` no envio

POST /v1/messages aceita content.media_id em vez de content.url:

{
  "type": "image",
  "to": "5511999998888",
  "content": {
    "media_id": "01HZTQUPLOAD...",
    "caption": "produto X"
  }
}

Mesmo padrao para image, audio, document, sticker. Forneca exatamente um de url OU media_id — passar os dois (ou nenhum) retorna 400.

Posse / re-uso

O upload e amarrado a sua app via uploaded_by_app_id. Outras apps nao conseguem usar nem baixar o seu upload.
Voce pode reusar o mesmo media_id em multiplas mensagens (eg. mandar a mesma imagem pra varios contatos sem re-uploadar).
Sem politica de expiry hoje — uploads ficam ate cleanup manual ou retencao futura.

Tamanho maximo

MEDIA_MAX_BYTES no env do hub (default 16MB). Acima disso, hub aborta o download e mensagem chega sem media_id.

Tempo de vida

Por enquanto, midia recebida fica em MinIO indefinidamente. Politica de retencao customizada esta em backlog (longo prazo).

Streaming pra cliente final

Se voce quer servir a midia pro browser do usuario final do seu app, proxy via seu backend (com sua sessao/cookies) e baixa via GET /v1/media/:id com sua api_key. Nao exponha a api_key do hub no front.