UC-019 — Analizzare Storico Messaggi

Campo	Valore
ID	UC-019
Obiettivo	Consultare lo storico messaggi ed esportare dati per report e audit
Canale	Tutti (SMS, RCS, WhatsApp)
Complessità	Intermedia
Tempo stimato	15 minuti
API coinvolte	GET /api/partner-gateway/v1/messages/history, POST /api/partner-gateway/v1/messages/history/export

Scenari reali

• Report mensile: Il marketing manager di TravelDream genera un report mensile con volumi di invio per canale e tasso di consegna.
• Analisi per canale: Il team di BrandCo confronta le performance di SMS vs WhatsApp per ottimizzare la strategia di comunicazione.
• Audit trail: Il compliance officer recupera lo storico completo dei messaggi inviati a un cliente specifico per una verifica GDPR.

Flusso di analisi

Il diagramma mostra il flusso di consultazione interattiva e l'export asincrono per dataset di grandi dimensioni.

Prerequisiti

• API Key attiva con permessi di lettura messaggi
• Almeno un messaggio inviato o ricevuto nell'account
• Per export di grandi volumi: pazientare per l'elaborazione asincrona

Step 1 — Consulta lo storico messaggi

Interroga lo storico con filtri per canale, data e stato di consegna.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-04-01&to=2026-04-09&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Storico messaggi

{
  "messages": [
    {
      "messageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "SMS",
      "direction": "OUTBOUND",
      "destination": "+393471234567",
      "sender": "TechStore",
      "body": "Ciao Marco, il tuo ordine #ORD-20260409 e stato confermato!",
      "status": "DELIVERED",
      "sendDate": "2026-04-09T10:15:00+02:00",
      "deliveryDate": "2026-04-09T10:15:03+02:00",
      "cost": 0.035,
      "parts": 1
    },
    {
      "messageId": "a2c4e6f8-1234-5678-9abc-def012345678",
      "channel": "SMS",
      "direction": "OUTBOUND",
      "destination": "+393489876543",
      "sender": "TechStore",
      "body": "Giulia, la tua spedizione e in arrivo domani!",
      "status": "DELIVERED",
      "sendDate": "2026-04-08T16:00:00+02:00",
      "deliveryDate": "2026-04-08T16:00:05+02:00",
      "cost": 0.035,
      "parts": 1
    }
  ],
  "total": 156,
  "page": 1,
  "totalPages": 8,
  "hasMore": true
}

:::tip Filtri disponibili Combina i parametri channel, from, to, status, destination e direction per restringere i risultati. Usa direction=INBOUND per vedere solo i messaggi ricevuti. :::

Dietro le quinte — Query e performance

1. Indicizzazione: Lo storico messaggi e indicizzato per channel, sendDate e destination per garantire query rapide anche su milioni di record.
2. Paginazione: I risultati sono paginati con limit e page. Il massimo e 100 messaggi per pagina.
3. Finestra temporale: La query senza filtro from/to restituisce gli ultimi 30 giorni per default. Lo storico completo e disponibile fino a 24 mesi.
4. Costi: Il campo cost mostra il costo unitario del messaggio nella valuta dell'account.

Step 2 — Esporta i dati per report

Per dataset di grandi dimensioni, avvia un export asincrono in formato CSV o JSON.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "channel": "SMS",
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "csv",
    "includeFields": ["messageId", "destination", "status", "sendDate", "deliveryDate", "cost"]
  }'

Response — Export avviato

{
  "exportId": "exp_x1y2z3w4",
  "status": "PROCESSING",
  "format": "csv",
  "estimatedRecords": 4520,
  "createdAt": "2026-04-09T16:00:00+02:00",
  "estimatedCompletionAt": "2026-04-09T16:02:00+02:00"
}

:::info Export asincrono L'export viene elaborato in background. Usa il exportId per verificare lo stato e scaricare il file quando pronto. :::

# Verifica lo stato dell'export
curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export/exp_x1y2z3w4" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Export completato

{
  "exportId": "exp_x1y2z3w4",
  "status": "COMPLETED",
  "format": "csv",
  "totalRecords": 4520,
  "fileSize": 524288,
  "downloadUrl": "https://exports.qlara.com/exp_x1y2z3w4/messages-2026-03.csv",
  "expiresAt": "2026-04-16T16:00:00+02:00",
  "completedAt": "2026-04-09T16:01:30+02:00"
}

Dietro le quinte — Processo di export

1. Coda: La richiesta di export viene inserita in una coda di elaborazione dedicata per non impattare le performance delle API real-time.
2. Generazione: Il sistema itera sullo storico applicando i filtri richiesti e genera il file nel formato scelto (CSV o JSON).
3. Storage: Il file viene salvato in uno storage temporaneo con URL firmato, accessibile senza autenticazione per 7 giorni.
4. Limiti: E possibile avere al massimo 3 export contemporanei. Gli export scaduti vengono automaticamente rimossi.

Risultato atteso

Step	Azione	Risultato
1	GET /messages/history	Lista paginata dei messaggi con filtri
2	POST /messages/history/export	Export asincrono avviato, exportId restituito
3	GET /messages/history/export/{id}	File pronto, downloadUrl disponibile

Esempio completo end-to-end

Scenario TravelDream: report mensile SMS di marzo.

# 1. Anteprima dei dati (primi 5 messaggi)
echo "=== Anteprima Storico Marzo ==="
curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-03-01&to=2026-03-31&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{total: .total, sample: [.messages[] | {destination, status, cost}]}'

# 2. Avvia export completo
EXPORT_ID=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "channel": "SMS",
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "csv"
  }' | jq -r '.exportId')

echo "Export avviato: $EXPORT_ID"

# 3. Attendi e scarica
sleep 120
DOWNLOAD_URL=$(curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export/${EXPORT_ID}" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.downloadUrl')

echo "Download: $DOWNLOAD_URL"

Varianti

Filtrare per destinatario specifico (audit GDPR)

Recupera tutti i messaggi inviati a un numero specifico per compliance:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?destination=%2B393471234567&from=2025-01-01&to=2026-04-09" \
  -H "X-Api-Key: YOUR_API_KEY"

Export in formato JSON

Per integrazioni programmatiche, esporta in JSON:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "json"
  }'

Errori comuni

400 Bad Request — Range temporale non valido

{
  "status": "fail",
  "data": {
    "dateRange": "Date range cannot exceed 12 months"
  }
}

Soluzione: Riduci l'intervallo temporale a massimo 12 mesi. Per periodi più lunghi, esegui più export separati.

429 Too Many Requests — Export in corso

{
  "status": "fail",
  "data": {
    "export": "Maximum concurrent exports (3) reached. Wait for current exports to complete."
  }
}

Soluzione: Attendi il completamento degli export in corso prima di avviarne di nuovi. Usa GET /messages/history/export/{id} per verificare lo stato.

Prossimi passi

• UC-011 — Export Delivery Reports: Esporta i report di consegna dettagliati
• UC-018 — Gestire l'Inbox: Gestisci le conversazioni in tempo reale
• UC-016 — Monitorare Credito e Abbonamento: Verifica i costi nel contesto dello storico

Riferimenti

• API Reference — Messages History