Media

Endpoints para gerenciamento de mídia: download de inbound e upload para Meta.

Base path: /v1/media

Modelo Media

Quando o gateway recebe uma mensagem com mídia (image, video, audio, document), ele:

1. Baixa do servidor de origem (Meta CDN ou Baileys S3).
2. Faz upload para o S3 interno (bucket configurado por env).
3. Cria registro MediaObject com TTL 7 dias.
4. No evento message:received, devolve media.downloadUrl apontando para GET /v1/media/:id (proxy do gateway, não o link cru).

{
  "id": "med-1234-5678-...",
  "messageId": "9a1b2c3d-...",
  "contentType": "image/jpeg",
  "sizeBytes": 234567,
  "filename": "foto.jpg",
  "expiresAt": "2026-05-28T14:00:00.000Z",
  "ackedAt": null,
  "deletedAt": null
}

O campo messageId é o UUID do gateway da mensagem que carregou essa mídia (o mesmo de message:received e media:available) — não o identificador nativo do WhatsApp.

TTL e ACK pattern:

• Mídia que não recebe ACK em 7 dias é deletada automaticamente (S3 lifecycle policy).
• Cliente pode fazer ACK explícito (POST /:id/ack) após baixar — gateway deleta na hora.
• Vencimento dispara evento media:expired no webhook.

---

GET /v1/media/:id

Redireciona para signed URL S3 (TTL 10min). Use em <img src>, <audio src>, ou clientes HTTP normais.

curl -L https://wpp.ogmma.com.br/v1/media/med-1234-... \
  -H "X-API-Key: ak_live_..." \
  -o foto.jpg

Response 302 — Location: https://s3.amazonaws.com/...?X-Amz-Signature=...

Errors

HTTP	Code	Quando
404	MEDIA_NOT_FOUND	ID inexistente ou de outra account
410	MEDIA_EXPIRED	TTL 7d passou
410	MEDIA_DELETED	ACK já fez delete explícito

---

GET /v1/media/:id/info

Metadata sem fazer download.

curl https://wpp.ogmma.com.br/v1/media/med-1234-.../info \
  -H "X-API-Key: ak_live_..."

Response 200 — mesmo objeto Media descrito acima.

---

POST /v1/media/:id/ack

ACK explícito: marca como ackedAt + dispara delete S3. Use depois de baixar e persistir do seu lado.

curl -X POST https://wpp.ogmma.com.br/v1/media/med-1234-.../ack \
  -H "X-API-Key: ak_live_..."

Response 204 (idempotente — chamadas múltiplas retornam 204)

---

POST /v1/media/upload

Upload de mídia para o Meta (gera mediaHandle reutilizável). Use quando você quer mandar a mesma mídia para vários destinatários sem rebaixar — cache de envio.

Headers

Header	Obrigatório	Descrição
X-API-Key	sim	—
X-Phone-Id	sim	UUID do phone WABA
Content-Type	sim	application/json

Body

Campo	Tipo	Obrigatório	Descrição
mediaUrl	URL	sim	URL pública HTTPS de onde baixar
mimeType	string	sim	Ex.: image/jpeg
filename	string	não	255 chars

curl -X POST https://wpp.ogmma.com.br/v1/media/upload \
  -H "X-API-Key: ak_live_..." \
  -H "X-Phone-Id: 5f7b2e1c-..." \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://cdn.acme.com/foto.jpg",
    "mimeType": "image/jpeg",
    "filename": "foto.jpg"
  }'

Response 201

{ "mediaHandle": "1234567890" }

Use o mediaHandle no content.mediaHandle de POST /v1/messages em vez de mediaUrl.

Limites Meta: 5MB image, 16MB video/audio, 100MB document. Para arquivos maiores em templates, use Resumable Upload abaixo.

---

POST /v1/media/upload/resumable

Upload reumível Meta. Necessário para arquivos ≥5MB usados como header_handle em templates ou em uploads grandes. Retorna um handle opaco (h:...) para usar em template.components.

Headers

Header	Obrigatório
X-API-Key	sim
X-Phone-Id	sim

Body

Campo	Tipo	Obrigatório
mediaUrl	URL	sim
mimeType	string	sim
fileName	string	sim
appId	string	sim (Meta App ID — geralmente o mesmo de META_APP_ID)

curl -X POST https://wpp.ogmma.com.br/v1/media/upload/resumable \
  -H "X-API-Key: ak_live_..." \
  -H "X-Phone-Id: 5f7b2e1c-..." \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://cdn.acme.com/video.mp4",
    "mimeType": "video/mp4",
    "fileName": "promo.mp4",
    "appId": "1234567890"
  }'

Response 201

{ "handle": "h:ABCD1234...", "sessionId": "...:abc" }

---

DELETE /v1/media/meta/:metaId

Deleta uma mídia no Meta (libera storage da WABA).

Headers: X-Phone-Id obrigatório.

curl -X DELETE https://wpp.ogmma.com.br/v1/media/meta/1234567890 \
  -H "X-API-Key: ak_live_..." \
  -H "X-Phone-Id: 5f7b2e1c-..."

Response 204