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), un canale per query
Complessità	Intermedia
Tempo stimato	15 minuti
API coinvolte	`GET /api/partner-gateway/v1/messages/history`, `POST /api/partner-gateway/v1/messages/history/export`, `GET /api/partner-gateway/v1/exports`, `GET /api/partner-gateway/v1/exports/{exportId}`

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 esporta i 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 le operazioni MESSAGES ed EXPORTS
Almeno un messaggio inviato tramite API
Per export di grandi volumi: pazientare per l'elaborazione asincrona

Step 1 — Consulta lo storico messaggi

channel, from e to sono obbligatori. Una data da sola copre l'intera giornata in UTC.

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

Response — Storico messaggi

La risposta è un array JSON, una voce per messaggio:

[
  {
    "customerMessageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "channel": "SMS",
    "destination": "+393471234567",
    "deliveryStatus": "DELIVERED",
    "deliveryStatusDescription": "delivered",
    "sendDate": "2026-04-09T08:15:00Z",
    "deliveryDate": "2026-04-09T08:15:03Z",
    "readDate": null
  },
  {
    "customerMessageId": "a2c4e6f8-1234-5678-9abc-def012345678",
    "channel": "SMS",
    "destination": "+393489876543",
    "deliveryStatus": "UNDELIVERABLE",
    "deliveryStatusDescription": "undeliverable",
    "sendDate": "2026-04-08T14:00:00Z",
    "deliveryDate": null,
    "readDate": null
  }
]

Formati data accettati

from e to accettano una data (2026-04-01, l'intera giornata UTC), una data-ora senza offset (2026-04-01T10:30:00, letta come UTC) oppure una data-ora ISO 8601 completa con offset (2026-04-01T00:00:00%2B02:00, 2026-04-09T23:59:59Z). Codifica il + come %2B. Qualsiasi altra forma riceve 400 con l'elenco dei formati accettati.

Dietro le quinte — Filtri e paginazione

Un canale per query: channel è SMS, RCS o WHATSAPP (senza distinzione tra maiuscole e minuscole). Per coprire più canali, esegui una query per canale.
Filtro di stato: aggiungi status con un nome di deliveryStatus per tenere un solo stato di consegna. I nomi dipendono dal canale (vedi la tabella degli stati): SMS usa ACCEPTED, REJECTED, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE e UNKNOWN; RCS usa DELIVERED, EXPIRED, ERROR, DISABLED, UNSUPPORTED e UNKNOWN; WhatsApp usa quelli di RCS più CONVERSATION_CLOSED. Uno stato che il canale non usa mai (per esempio ERROR su SMS) restituisce un array vuoto.
Paginazione: page parte da 0 e limit vale 20 per default. La risposta è un array semplice: sei sull'ultima pagina quando contiene meno elementi di limit.
Intervallo obbligatorio: from e to sono obbligatori e from non può essere successivo a to; altrimenti l'API risponde 400.
Filtri per mittente e destinatario sono disponibili sull'export, non sulla query.

Step 2 — Esporta i dati per report

Per dataset di grandi dimensioni, accoda un export asincrono in CSV. Le date sono ISO 8601 con offset; sender e recipient sono filtri opzionali.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "startDateTime": "2026-03-01T00:00:00+01:00",
    "endDateTime": "2026-03-31T23:59:59+02:00"
  }'

Response — Export accodato

202 Accepted con corpo vuoto. L'export copre tutti i canali e solo i messaggi inviati tramite API.

Export asincrono

Il file viene generato in background. Seguilo tramite gli endpoint di export: la lista ti dice quando è pronto, il dettaglio ti dà l'URL di download.

# Elenca i tuoi export, dal più recente
curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/exports?page=0&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Lista export

{
  "data": [
    {
      "id": 369,
      "type": null,
      "detail": {
        "type": "DELIVERY_REPORT",
        "exportFormat": "CSV",
        "startDateTime": "2026-02-28T23:00:00Z",
        "endDateTime": "2026-03-31T21:59:59Z",
        "sendType": "API"
      },
      "status": null,
      "createdAt": "2026-04-09 14:00:12.200+0000",
      "expiresAt": "2026-04-16 14:00:12.199+0000",
      "isAvailableForDownload": true
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 1,
  "totalPages": 1
}

Un export dello storico compare come DELIVERY_REPORT con sendType API. Quando isAvailableForDownload è true, recupera l'URL di download:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/exports/369" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — URL di download

{
  "url": "https://storage.example.com/exports/369/delivery-report-2026-03.csv?X-Amz-Expires=3600&X-Amz-Signature=..."
}

Dietro le quinte — Processo di export

Coda: la richiesta viene inserita in una coda dedicata per non impattare le API real-time.
Ambito: l'export copre tutti i canali (SMS, RCS, WhatsApp) ma solo i messaggi inviati tramite API, gli stessi mostrati da GET /messages/history.
Storage: il file è conservato dietro un URL firmato che scade; expiresAt indica fino a quando. Un export scaduto può essere rigenerato con POST /exports/{exportId}.
Formato: solo CSV.

Risultato atteso

Step	Azione	Risultato
1	`GET /messages/history`	Array di messaggi per canale e intervallo di date
2	`POST /messages/history/export`	`202 Accepted`, export accodato
3	`GET /exports`	L'export compare con `isAvailableForDownload: true`
4	`GET /exports/{exportId}`	URL di download

Esempio completo end-to-end

Scenario TravelDream: report mensile SMS di marzo.

BASE="https://api.qlara.ai/api/partner-gateway/v1"

# 1. Anteprima dei dati (primi 5 messaggi)
echo "=== Anteprima Storico Marzo ==="
curl -s -X GET "$BASE/messages/history?channel=SMS&from=2026-03-01&to=2026-03-31&page=0&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.[] | {destination, deliveryStatus, sendDate}'

# 2. Accoda l'export completo (202, corpo vuoto)
curl -s -o /dev/null -w "export accodato: HTTP %{http_code}\n" -X POST "$BASE/messages/history/export" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"startDateTime": "2026-03-01T00:00:00+01:00", "endDateTime": "2026-03-31T23:59:59+02:00"}'

# 3. Attendi, poi prendi l'export più recente quando è pronto
sleep 60
EXPORT_ID=$(curl -s -X GET "$BASE/exports?page=0&limit=1" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data[0] | select(.isAvailableForDownload) | .id')

# 4. Scarica
DOWNLOAD_URL=$(curl -s -X GET "$BASE/exports/${EXPORT_ID}" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.url')
echo "Download: $DOWNLOAD_URL"

Varianti

Solo i messaggi falliti

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-04-01&to=2026-04-09&status=UNDELIVERABLE" \
  -H "X-Api-Key: YOUR_API_KEY"

Un SMS può fallire anche come REJECTED o EXPIRED: esegui una query per stato per coprirli tutti. ERROR è uno stato di RCS e WhatsApp, quindi status=ERROR su SMS restituisce sempre un array vuoto.

L'endpoint di consultazione non ha un filtro per destinatario; usa l'export con recipient:

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "startDateTime": "2025-01-01T00:00:00+01:00",
    "endDateTime": "2026-04-09T23:59:59+02:00",
    "recipient": "+393471234567"
  }'

Errori comuni

400 Bad Request — Parametri mancanti

{
  "status": "fail",
  "data": "Required query params: 'channel' (RCS, WHATSAPP, SMS), 'from' and 'to' (yyyy-MM-dd (a whole day, UTC), yyyy-MM-ddTHH:mm:ss (UTC) or ISO-8601 with an offset such as 2025-01-15T00:00:00+01:00 or 2025-01-15T00:00:00Z)"
}

Soluzione: passa tutti e tre i parametri. channel è uno tra SMS, RCS, WHATSAPP.

400 Bad Request — Data in un formato sconosciuto

{
  "status": "fail",
  "data": "Invalid 'from': '27/08/2026'. Accepted formats: yyyy-MM-dd (a whole day, UTC), yyyy-MM-ddTHH:mm:ss (UTC) or ISO-8601 with an offset such as 2025-01-15T00:00:00+01:00 or 2025-01-15T00:00:00Z"
}

Soluzione: usa uno dei formati elencati nel messaggio e codifica il + dell'offset come %2B.

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

Scenari reali​

Flusso di analisi​

Prerequisiti​

Step 1 — Consulta lo storico messaggi​

Response — Storico messaggi​

Step 2 — Esporta i dati per report​

Response — Export accodato​

Response — Lista export​

Response — URL di download​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Solo i messaggi falliti​

Messaggi inviati a un destinatario (audit GDPR)​

Errori comuni​

400 Bad Request — Parametri mancanti​

400 Bad Request — Data in un formato sconosciuto​

Prossimi passi​

Riferimenti​