> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waspytech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media

> Resolver mensajes con media (audio, imagen, video, documento) a URLs descargables.

Cuando un contacto te manda un mensaje con media, Waspy descarga el archivo de Meta automáticamente y lo guarda en su storage. Tu bot recibe el mensaje vía webhook (o GET REST) con dos campos útiles:

* `mediaId` — UUID estable que podés resolver a URL firmada vía `GET /media/:id`
* `mediaKey` — clave interna del object storage (alternativa)

**Scope requerido:** `media:read`.

## GET /media/:id

Devuelve una URL firmada de corta duración para descargar el archivo. La URL expira a los pocos minutos — refetch cuando la necesites de nuevo.

```bash theme={null}
curl https://api.waspytech.com/api/v2/media/{mediaId} \
  -H "Authorization: Bearer wspy_..."
```

Respuesta:

```json theme={null}
{
  "data": {
    "id": "uuid",
    "url": "https://storage.googleapis.com/...?X-Goog-Signature=...",
    "expiresIn": 3600,
    "mimeType": "audio/ogg",
    "fileName": "voice.ogg"
  },
  "meta": { "requestId": "..." }
}
```

**Tenant-scoped:** si el `mediaId` pertenece a otro tenant, devuelve 404.

## GET /media/by-key

Variante por GCS object key, útil cuando el payload del mensaje sólo expone `mediaKey`. Tenant-scoped: la key debe empezar con tu `tenantId`.

```bash theme={null}
curl "https://api.waspytech.com/api/v2/media/by-key?key=<tenantId>/<uuid>.jpg" \
  -H "Authorization: Bearer wspy_..."
```

## Flujo típico para un bot

1. Recibís webhook `message.received` con `type: "audio"` y `mediaId`.
2. (Si `mediaId` está null al recibirlo, esperás 1-2 segundos y refetcheás el mensaje vía `GET /messages/:id`.)
3. `GET /media/:id` → URL firmada.
4. Descargás el archivo desde la URL firmada antes de que expire.

## Tipos de media soportados

`image`, `video`, `audio`, `document`, `sticker`. Para cada tipo, el `mimeType` del response corresponde al original que envió Meta.