Message History
Consulta ed esporta lo storico completo dei messaggi inviati.
Elenca storico invii
Restituisce un elenco paginato dei messaggi inviati per il canale e l'intervallo di date indicati, permettendoti di consultare l'intero storico degli invii con filtri flessibili. Usa questo endpoint quando devi rivedere gli invii passati, verificare le performance di consegna in una finestra temporale o costruire dashboard e report sui tassi di consegna dei messaggi. Il parametro channel è obbligatorio e limita i risultati a un singolo canale di messaggistica (SMS, RCS o WHATSAPP). Per ottenere lo storico su più canali, effettua una richiesta separata per ciascun canale. I parametri from e to definiscono l'intervallo di date di invio (estremi inclusi) e sono obbligatori. Formati accettati: una data sola (2025-01-15, che indica l'intera giornata in UTC: 00:00:00Z come from, 23:59:59Z come to), una data-ora senza offset (2025-01-15T10:30:00, interpretata come UTC) oppure una data-ora ISO-8601 completa con offset (2025-01-15T00:00:00+01:00 o 2025-06-15T23:59:59Z). Ricorda di codificare in percent-encoding il segno + dell'offset come %2B: un + non codificato viene decodificato come spazio. Un valore che non rispetta nessuno di questi formati, o un from successivo a to, riceve in risposta un 400 con un messaggio che indica il parametro e i formati accettati. Il parametro opzionale status ti permette di filtrare per uno specifico stato di consegna: ACCEPTED, REJECTED, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ERROR, DISABLED, UNSUPPORTED, CONVERSATION_CLOSED o UNKNOWN. Quali possono comparire dipende dal canale — vedi la tabella Stati di Consegna nella panoramica dell'API. Ometti questo parametro per restituire i messaggi in tutti gli stati. La paginazione è controllata dai parametri page e limit. Le pagine partono da 0 (la prima pagina è page=0). La dimensione di pagina predefinita è 20 se limit non è specificato. Per scorrere tutti i risultati, incrementa il parametro page finché la risposta non restituisce meno elementi del limit richiesto, il che indica che hai raggiunto l'ultima pagina. La risposta è un array JSON di oggetti DeliveryStatusResponse, che può essere vuoto se nessun messaggio corrisponde ai filtri indicati. Per intervalli di date ampi con molti messaggi, valuta l'uso dell'endpoint di esportazione (POST /partner-gateway/v1/messages/history/export) per generare un file CSV scaricabile invece di paginare tra migliaia di risultati. Risposte di errore: 400 per un channel, from o to mancante o malformato; 500 indica un errore imprevisto lato server; riprova dopo una breve attesa.
Esporta lo storico invii come CSV
Accoda un'esportazione CSV asincrona dei messaggi inviati tramite API nell'intervallo di date indicato. Questo endpoint è pensato per scenari di estrazione massiva di dati e di reportistica in cui paginare attraverso l'endpoint di elenco dello storico sarebbe poco pratico. L'esportazione copre tutti i canali (SMS, RCS, WhatsApp) in un unico file, quindi non devi richiedere esportazioni separate per ciascun canale. Sono inclusi solo i messaggi inviati tramite API; i messaggi inviati tramite altre interfacce (come gli strumenti per le campagne o la console web) sono esclusi. Il corpo della richiesta richiede startDateTime e endDateTime come stringhe ISO-8601 OffsetDateTime (ad esempio: 2025-01-01T00:00:00+01:00). Puoi facoltativamente filtrare per mittente o destinatario. Questo endpoint restituisce subito HTTP 202 Accepted, a indicare che il job di esportazione è stato messo in coda ma non è ancora completato. L'esportazione viene eseguita in modo asincrono in background e può richiedere da pochi secondi a diversi minuti, a seconda del volume di dati nell'intervallo di date richiesto. Per verificare lo stato della tua esportazione e recuperare l'URL di download quando è pronta, interroga l'endpoint GET /partner-gateway/v1/exports. Quell'endpoint indicherà se l'esportazione è ancora in corso, completata (con un link di download) o fallita. Il file CSV generato include colonne per ID messaggio, canale, destinazione, stato di consegna, data di invio, data di consegna e altri metadati rilevanti. Errori comuni: richiedere intervalli di date molto ampi (mesi di dati) può comportare tempi di elaborazione lunghi. Se ti serve solo un sottoinsieme dei dati, valuta di restringere l'intervallo di date o di usare invece l'endpoint della lista paginata (GET /partner-gateway/v1/messages/history). Risposte di errore: viene restituito 400 se il corpo della richiesta è malformato o mancano campi obbligatori. 500 indica un errore imprevisto lato server; riprova dopo una breve attesa.