UC-015 — Upload and Manage Media

Field	Value
ID	UC-015
Goal	Upload, list and remove media files from the library
Channel	RCS, WhatsApp
Complexity	Basic
Estimated time	10 minutes
APIs involved	POST /api/partner-gateway/v1/media, GET /api/partner-gateway/v1/media, DELETE /api/partner-gateway/v1/media

Real-world scenarios

• Upload image for RCS: FashionOutlet uploads images of the new collection to send them via RCS Rich Card.
• Manage media library: The TravelDream marketing team organizes its library of promotional images, checking which are still in use.
• Delete obsolete media: At the end of a campaign, the team removes seasonal images to keep the library tidy.

Media management flow

The diagram shows the media file lifecycle: upload, listing and removal.

Prerequisites

• Active API Key with media management permissions
• Image file in a supported format (JPEG, PNG, GIF -- max 5 MB)
• For RCS: recommended dimensions 1440x1440 px (square images) or 1440x720 px (landscape)

Step 1 — Upload a media file

Send the file via 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 uploaded

{
  "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 Use the URL in RCS messages The url field is the public address to insert in the mediaUrl field of RCS Rich Cards. Save it in your CMS associated with the campaign. :::

Behind the scenes — File processing

1. Validation: The gateway verifies the MIME type, file size and image resolution.
2. Optimization: The image is compressed while maintaining visual quality (JPEG quality 85%) and converted to optimal formats for each channel.
3. CDN Distribution: The file is replicated across multiple CDN nodes to ensure low latency delivery.
4. Thumbnail: A reduced version (300x300 px) is automatically generated for dashboard previews.
5. Scanning: The file is analyzed to verify the absence of malicious content (malware scan).

Step 2 — List uploaded media

Retrieve the list of files in your media library.

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

Response — Media list

{
  "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 — Delete obsolete media

Remove a file from the library when it is no longer needed.

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 deleted

{
  "mediaId": "med_1a2b3c4d5e6f",
  "status": "DELETED",
  "deletedAt": "2026-04-09T16:00:00+02:00"
}

Behind the scenes — Deletion and cache

1. Soft delete: The file is marked as deleted in the database but remains in the CDN for 24 hours to handle messages already in the queue.
2. CDN Purge: After 24 hours, the file is removed from all CDN nodes.
3. Queued messages: If a queued message references a deleted media, the gateway replaces the image with a generic placeholder.
4. Audit: The deletion event is recorded in the log with the mediaId and the user who performed the operation.

Expected result

Step	Action	Result
1	POST /media	File uploaded, mediaId and url returned
2	GET /media	Full media list with metadata
3	DELETE /media	Media removed, status: "DELETED"

Complete end-to-end example

Scenario FashionOutlet: upload an image and use it in an RCS Rich Card.

# 1. Upload the promotional image
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. Verify it is in the library
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. Use the URL in the RCS Rich Card (see UC-002)
echo "Ready for RCS sending with mediaUrl: $MEDIA_URL"

Variants

Upload a video

For channels that support video (RCS), upload MP4 files (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"

Common errors

413 Payload Too Large — File too large

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

Solution: Compress the image or reduce its resolution. For RCS Rich Cards, 1440px width is sufficient.

415 Unsupported Media Type — Unsupported format

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

Solution: Convert the file to one of the supported formats before uploading.

Next steps

• UC-002 — Send RCS Rich Card: Use the uploaded media in an RCS Rich Card
• UC-003 — Send WhatsApp Template: Associate media with WhatsApp templates
• UC-014 — API Key Management: Manage access keys

References

• API Reference — Media