Media

Descargar archivos adjuntos de conversaciones (imagenes, documentos, audio, video)

Los archivos que envian tus contactos por WhatsApp (fotos, PDFs, audios, videos) se almacenan de forma segura y se pueden descargar usando tu API key.

Como funciona

Cuando un contacto envia un archivo, Mirlo lo descarga y almacena de forma permanente
En el mensaje, el campo content.file.uri contiene una referencia interna al archivo
Con esa referencia puedes descargar el archivo via la API de Documents

Obtener la referencia del archivo

Al listar mensajes de una conversacion, los mensajes con archivos adjuntos tienen esta estructura:

{
  "id": "bed12137-7066-49d3-852f-4462eb33f4ac",
  "content": {
    "kind": "image",
    "type": "file",
    "file": {
      "uri": "internal://organizations/{organization_id}/attachments/abc123def456",
      "name": "foto_ine.jpg",
      "mime_type": "image/jpeg",
      "size": 31412
    }
  }
}

El campo content.file.uri empieza con internal://. Para descargar el archivo, quita ese prefijo y usa el resto como key.

Descargar el archivo

# 1. Extraer la key del URI (quitar "internal://")
# URI:  internal://organizations/{org_id}/attachments/abc123def456
# Key:  organizations/{org_id}/attachments/abc123def456

# 2. Descargar
curl -X POST "https://api.mirlo.com/v2/documents/objects/download" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "organizations/{organization_id}/attachments/abc123def456"}' \
  --output archivo_descargado.jpg

La respuesta es el archivo binario con el Content-Type correspondiente (ej: image/jpeg, application/pdf).

Listar archivos

curl "https://api.mirlo.com/v2/documents/objects" \
  -H "X-API-Key: sk_live_tu_api_key"

Retorna los archivos de tu organizacion con su metadata (id, key, name, content_type, size).

Obtener metadata de un archivo

Por ID

curl "https://api.mirlo.com/v2/documents/objects/{object_id}" \
  -H "X-API-Key: sk_live_tu_api_key"

Por key

curl "https://api.mirlo.com/v2/documents/objects/by-key?key=organizations/{organization_id}/attachments/abc123" \
  -H "X-API-Key: sk_live_tu_api_key"

Ejemplo completo

# Paso 1: Obtener mensajes de una conversacion
MESSAGES=$(curl -s "https://api.mirlo.com/v1/messages?conversation_id={conversation_id}" \
  -H "X-API-Key: sk_live_tu_api_key")

# Paso 2: Extraer el URI del archivo (ejemplo con jq)
FILE_URI=$(echo $MESSAGES | jq -r '.data[] | select(.content.file) | .content.file.uri' | head -1)

# Paso 3: Quitar el prefijo "internal://"
KEY=$(echo $FILE_URI | sed 's|^internal://||')

# Paso 4: Descargar
curl -X POST "https://api.mirlo.com/v2/documents/objects/download" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"$KEY\"}" \
  --output archivo.jpg

Seguridad

Cada API key solo puede acceder a los archivos de su propia organizacion. Intentar descargar archivos de otra organizacion retorna 404.

Referencia de Endpoints

Metodo	Ruta	Descripcion
`GET`	`/v2/documents/objects`	Listar archivos de la organizacion
`GET`	`/v2/documents/objects/:id`	Metadata por ID
`GET`	`/v2/documents/objects/by-key`	Metadata por key
`POST`	`/v2/documents/objects/download`	Descargar archivo

En esta pagina