Passa al contenuto principale

UC-015 — Upload e Gestione Media

CampoValore
IDUC-015
ObiettivoCaricare, elencare e rimuovere file media dalla libreria
CanaleRCS, WhatsApp
ComplessitàBase
Tempo stimato10 minuti
API coinvoltePOST /api/partner-gateway/v1/media, GET /api/partner-gateway/v1/media, DELETE /api/partner-gateway/v1/media

Scenari reali​

  • Caricare immagine per RCS: L'azienda FashionOutlet carica le immagini della nuova collezione per inviarle tramite Rich Card RCS.
  • Gestire libreria media: Il team marketing di TravelDream organizza la propria libreria di immagini promozionali, verificando quali sono ancora in uso.
  • Eliminare media obsoleti: A fine campagna, il team rimuove le immagini stagionali per mantenere la libreria ordinata.

Flusso di gestione media​

Il diagramma mostra il ciclo di vita di un file media: upload, consultazione e rimozione.

Prerequisiti​

  • API Key attiva con permessi di gestione media
  • File immagine in formato supportato (JPEG, PNG, GIF — max 5 MB)
  • Per RCS: dimensioni consigliate 1440x1440 px (immagini quadrate) o 1440x720 px (landscape)

Step 1 — Carica un file media​

Invia il file tramite multipart form-data.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/promo-estate-2026.jpg" \
  -F "name=promo-estate-2026" \
  -F "description=Banner promozione estate 2026 - Collezione mare"

Response — Media caricato​

{
  "mediaId": "med_7f3a2b1c4d5e",
  "name": "promo-estate-2026",
  "description": "Banner promozione estate 2026 - Collezione mare",
  "url": "https://media.qlara.com/v1/med_7f3a2b1c4d5e/promo-estate-2026.jpg",
  "mimeType": "image/jpeg",
  "size": 245760,
  "width": 1440,
  "height": 720,
  "createdAt": "2026-04-09T11:00:00+02:00"
}

:::tip Usa l'URL nei messaggi RCS Il campo url e l'indirizzo pubblico da inserire nel campo mediaUrl delle Rich Card RCS. Salvalo nel tuo CMS associato alla campagna. :::

Dietro le quinte — Elaborazione del file
  1. Validazione: Il gateway verifica tipo MIME, dimensioni del file e risoluzione dell'immagine.
  2. Ottimizzazione: L'immagine viene compressa mantenendo la qualita visiva (JPEG quality 85%) e convertita in formati ottimali per ogni canale.
  3. CDN Distribution: Il file viene replicato su più nodi CDN per garantire bassa latenza nella consegna.
  4. Thumbnail: Viene generata automaticamente una versione ridotta (300x300 px) per le anteprime nella dashboard.
  5. Scansione: Il file viene analizzato per verificare l'assenza di contenuti malevoli (malware scan).

Step 2 — Elenca i media caricati​

Recupera la lista dei file presenti nella tua libreria media.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Lista media​

{
  "media": [
    {
      "mediaId": "med_7f3a2b1c4d5e",
      "name": "promo-estate-2026",
      "mimeType": "image/jpeg",
      "size": 245760,
      "url": "https://media.qlara.com/v1/med_7f3a2b1c4d5e/promo-estate-2026.jpg",
      "createdAt": "2026-04-09T11:00:00+02:00"
    },
    {
      "mediaId": "med_1a2b3c4d5e6f",
      "name": "logo-brand-2026",
      "mimeType": "image/png",
      "size": 52480,
      "url": "https://media.qlara.com/v1/med_1a2b3c4d5e6f/logo-brand-2026.png",
      "createdAt": "2026-03-15T09:30:00+01:00"
    }
  ],
  "total": 2
}

Step 3 — Elimina un media obsoleto​

Rimuovi un file dalla libreria quando non e più necessario.

curl -X DELETE https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "mediaId": "med_1a2b3c4d5e6f"
  }'

Response — Media eliminato​

{
  "mediaId": "med_1a2b3c4d5e6f",
  "status": "DELETED",
  "deletedAt": "2026-04-09T16:00:00+02:00"
}
Dietro le quinte — Eliminazione e cache
  1. Soft delete: Il file viene marcato come eliminato nel database, ma resta nel CDN per 24 ore per gestire messaggi già in coda.
  2. Purge CDN: Dopo 24 ore, il file viene rimosso da tutti i nodi CDN.
  3. Messaggi in coda: Se un messaggio in coda fa riferimento a un media eliminato, il gateway sostituisce l'immagine con un placeholder generico.
  4. Audit: L'evento di eliminazione viene registrato nel log con il mediaId e l'utente che ha eseguito l'operazione.

Risultato atteso​

StepAzioneRisultato
1POST /mediaFile caricato, mediaId e url restituiti
2GET /mediaLista completa dei media con metadati
3DELETE /mediaMedia rimosso, status: "DELETED"

Esempio completo end-to-end​

Scenario FashionOutlet: carica immagine e usala in una Rich Card RCS.

# 1. Carica l'immagine promozionale
MEDIA_URL=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./summer-collection.jpg" \
  -F "name=summer-collection-2026" | jq -r '.url')

echo "Media URL: $MEDIA_URL"

# 2. Verifica che sia nella libreria
curl -s -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.media[] | select(.name == "summer-collection-2026")'

# 3. Usa l'URL nella Rich Card RCS (vedi UC-002)
echo "Pronto per l'invio RCS con mediaUrl: $MEDIA_URL"

Varianti​

Upload di un video​

Per i canali che supportano video (RCS), carica file MP4 (max 10 MB):

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/promo-video.mp4" \
  -F "name=promo-video-estate" \
  -F "description=Video promozionale 15 secondi"

Errori comuni​

413 Payload Too Large — File troppo grande​

{
  "status": "fail",
  "data": {
    "file": "File size exceeds maximum allowed (5 MB for images, 10 MB for videos)"
  }
}

Soluzione: Comprimi l'immagine o riducine la risoluzione. Per le Rich Card RCS, 1440px di larghezza e sufficiente.

415 Unsupported Media Type — Formato non supportato​

{
  "status": "fail",
  "data": {
    "file": "Unsupported media type. Allowed: image/jpeg, image/png, image/gif, video/mp4"
  }
}

Soluzione: Converti il file in uno dei formati supportati prima dell'upload.

Prossimi passi​

Riferimenti​