Passa al contenuto principale

UC-026 — Download Media da Messaggi Inbound

CampoValore
IDUC-026
ObiettivoRicevere messaggi inbound con media e scaricare i file allegati
CanaleWhatsApp, RCS
Complessità⭐⭐ Intermedio
Tempo stimato15 minuti
API coinvolteWebhook INBOUND, GET /api/files/{mediaKey}

Scenari reali​

  • AssicuraFacile — Foto sinistro: Il cliente invia via WhatsApp le foto del danno alla propria auto. L'operatore le scarica per allegare alla pratica assicurativa.
  • StudioLegale Rossi — Documenti via WhatsApp: Un cliente invia un contratto PDF per una revisione rapida. Lo studio lo scarica e archivia nel gestionale documentale.
  • RadioTaxi Milano — Messaggi vocali: L'autista invia un messaggio vocale con le indicazioni per il punto di ritiro. Il sistema lo scarica e lo trascrive automaticamente.

Flusso del download media​

Il diagramma illustra il flusso completo: l'utente invia un file multimediale, il gateway lo notifica al tuo server tramite webhook con la mediaKey, e la tua applicazione scarica il file tramite l'endpoint dedicato.

Prerequisiti​

  • API Key attiva con permessi di lettura messaggi
  • Endpoint webhook configurato per eventi INBOUND (vedi guida Webhook)
  • Numero WhatsApp Business o RCS agent registrato sulla piattaforma
  • Storage locale o cloud (S3, Azure Blob) per il salvataggio dei file

Step 1 — Configura il webhook per messaggi inbound​

Assicurati che il tuo endpoint webhook sia registrato per ricevere eventi di tipo INBOUND. Quando un utente invia un messaggio con allegato, riceverai una notifica come questa:

{
  "channel": "WHATSAPP",
  "eventType": "INBOUND",
  "messageId": "wamid.HBgNMzkzNDcxMjM0NTY3FQIAEhggQTJDNEU2RjgtMTIzNC01Njc4",
  "from": "+393471234567",
  "to": "+393801234567",
  "timestamp": "2026-04-09T14:22:10Z",
  "content": {
    "type": "IMAGE",
    "caption": "Foto danno paraurti anteriore",
    "mimeType": "image/jpeg",
    "mediaKey": "mk_a1b2c3d4e5f6g7h8i9j0"
  }
}
Tipi di media supportati

I tipi supportati includono IMAGE (JPEG, PNG), DOCUMENT (PDF, DOCX), AUDIO (OGG, MP3), VIDEO (MP4) e STICKER. Ogni tipo ha limiti di dimensione specifici definiti dal carrier.

Step 2 — Scarica il file media tramite mediaKey​

Usa la mediaKey ricevuta nel webhook per ottenere il file:

curl -X GET "https://api.qlara.ai/api/files/mk_a1b2c3d4e5f6g7h8i9j0" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — URL di download​

{
  "mediaKey": "mk_a1b2c3d4e5f6g7h8i9j0",
  "url": "https://cdn.agiletelecom.com/media/mk_a1b2c3d4e5f6g7h8i9j0.jpg?token=eyJhbG...&expires=1744210930",
  "mimeType": "image/jpeg",
  "fileSize": 245780,
  "expiresAt": "2026-04-09T15:22:10Z"
}
URL con scadenza

L'URL pre-signed ha una durata limitata (tipicamente 60 minuti). Scarica il file immediatamente dopo aver ricevuto l'URL. Se l'URL e scaduto, ripeti la chiamata GET /api/files/{mediaKey} per ottenerne uno nuovo.

Step 3 — Download e salvataggio del file​

Usa l'URL pre-signed per scaricare il file effettivo:

curl -o "sinistro_paraurti.jpg" \
  "https://cdn.agiletelecom.com/media/mk_a1b2c3d4e5f6g7h8i9j0.jpg?token=eyJhbG...&expires=1744210930"
Dietro le quinte — Ciclo di vita del media
  1. Ricezione: Quando l'utente invia un file, il carrier (Meta per WhatsApp, Google per RCS) lo memorizza temporaneamente sui propri server.
  2. Notifica: Il gateway riceve il messaggio inbound e genera una mediaKey univoca che mappa il file sul carrier.
  3. Proxy sicuro: La chiamata GET /api/files/{mediaKey} non scarica il file direttamente dal gateway, ma restituisce un URL pre-signed che punta al CDN. Questo evita di sovraccaricare il gateway con trasferimenti di file di grandi dimensioni.
  4. Scadenza: I file sui server del carrier hanno una retention limitata (tipicamente 30 giorni per WhatsApp). Dopo la scadenza, il file non sara più disponibile. Scaricalo e archivialo il prima possibile.
  5. Dimensioni: WhatsApp supporta file fino a 16 MB per immagini, 100 MB per video e 100 MB per documenti.

Step 4 — Processa e archivia​

Una volta scaricato, il file puo essere processato secondo le esigenze:

# Esempio: salvataggio su directory organizzata per data e pratica
PRATICA_ID="SIN-2026-04-0892"
DATA=$(date +%Y%m%d)
DEST_DIR="/archivio/sinistri/${PRATICA_ID}/${DATA}"

mkdir -p "$DEST_DIR"
mv sinistro_paraurti.jpg "${DEST_DIR}/foto_001.jpg"

echo "File archiviato in: ${DEST_DIR}/foto_001.jpg"

Risultato atteso​

StepAzioneRisultato
1Webhook INBOUND ricevutoeventType: "INBOUND", content.mediaKey presente
2GET /api/files/{mediaKey}URL pre-signed con mimeType e fileSize
3Download da URL pre-signedFile binario scaricato correttamente
4ArchiviazioneFile salvato nello storage aziendale

Esempio completo end-to-end​

Ecco lo scenario AssicuraFacile completo, dalla ricezione del webhook al salvataggio:

#!/bin/bash
# Script di gestione media inbound per AssicuraFacile

MEDIA_KEY="mk_a1b2c3d4e5f6g7h8i9j0"
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.qlara.ai"

# 1. Ottieni l'URL di download
RESPONSE=$(curl -s -X GET "${BASE_URL}/api/files/${MEDIA_KEY}" \
  -H "X-Api-Key: ${API_KEY}")

DOWNLOAD_URL=$(echo "$RESPONSE" | jq -r '.url')
MIME_TYPE=$(echo "$RESPONSE" | jq -r '.mimeType')
FILE_SIZE=$(echo "$RESPONSE" | jq -r '.fileSize')

echo "Tipo: ${MIME_TYPE}, Dimensione: ${FILE_SIZE} bytes"

# 2. Scarica il file
EXTENSION="${MIME_TYPE##*/}"
curl -s -o "media_inbound.${EXTENSION}" "$DOWNLOAD_URL"

echo "File scaricato: media_inbound.${EXTENSION}"

# 3. Archivia nel gestionale
PRATICA_ID="SIN-2026-04-0892"
mv "media_inbound.${EXTENSION}" "/archivio/sinistri/${PRATICA_ID}/"

echo "Archiviato nella pratica ${PRATICA_ID}"

Varianti​

Gestione di messaggi con più allegati​

Se l'utente invia più file, riceverai un webhook per ciascun allegato. Itera sulle mediaKey:

MEDIA_KEYS=("mk_aaa111" "mk_bbb222" "mk_ccc333")

for KEY in "${MEDIA_KEYS[@]}"; do
  URL=$(curl -s -X GET "${BASE_URL}/api/files/${KEY}" \
    -H "X-Api-Key: ${API_KEY}" | jq -r '.url')
  curl -s -o "file_${KEY}.jpg" "$URL"
done

Errori comuni​

404 Not Found — mediaKey non valida o scaduta​

{
  "status": "fail",
  "data": {
    "error": "Media not found or expired"
  }
}

Soluzione: La mediaKey potrebbe essere scaduta (retention del carrier superata). Verifica di processare i webhook tempestivamente. I file WhatsApp sono disponibili per circa 30 giorni.

401 Unauthorized — API Key mancante​

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva.

URL pre-signed scaduto​

Se il download fallisce con errore HTTP 403, l'URL pre-signed e scaduto. Richiedi un nuovo URL:

# L'URL e scaduto, richiedi uno nuovo
curl -X GET "https://api.qlara.ai/api/files/mk_a1b2c3d4e5f6g7h8i9j0" \
  -H "X-Api-Key: YOUR_API_KEY"

Prossimi passi​

Riferimenti​