Monitoraggio SMS via API: webhook, delivery report e stati dei messaggi

Quando un’applicazione invia un SMS tramite API, il processo non si conclude nel momento in cui il provider restituisce una risposta HTTP positiva. Quella risposta conferma semplicemente che la richiesta è stata ricevuta e accettata dalla piattaforma di messaggistica. Non fornisce però alcuna garanzia sul fatto che il messaggio sia stato effettivamente recapitato al destinatario.

Tra il momento dell’invio e quello della consegna intervengono numerosi elementi: il gateway SMS, le reti degli operatori mobili, i meccanismi di routing, eventuali procedure di retry e, infine, il dispositivo del destinatario. In ogni fase possono verificarsi ritardi, errori o condizioni che impediscono la corretta consegna del messaggio.

Per molte applicazioni aziendali questo aspetto è tutt’altro che secondario. Un sistema che invia notifiche operative, codici OTP, conferme di prenotazione, alert di sicurezza o comunicazioni transazionali non può limitarsi a sapere che il messaggio è stato inviato. Deve poter verificare che cosa sia accaduto successivamente.

Il messaggio è stato consegnato? È ancora in attesa di essere recapitato? L’operatore ha restituito un errore? Il numero risulta inesistente o non raggiungibile? È necessario effettuare un nuovo tentativo di invio oppure attivare un canale alternativo?

Per rispondere a queste domande le API SMS oggi mettono a disposizione una serie di strumenti di monitoraggio che consentono alle applicazioni di osservare l’intero ciclo di vita del messaggio. I principali sono:

• i Delivery Report (DLR), che comunicano l’esito della consegna;
• i webhook, che notificano automaticamente gli aggiornamenti di stato;
• gli stati dei messaggi, che descrivono le diverse fasi attraversate dall’SMS durante il processo di consegna.

Comprendere il funzionamento di questi meccanismi è fondamentale per progettare integrazioni affidabili, costruire workflow robusti e gestire correttamente le situazioni di errore. In questo articolo vedremo come funzionano webhook, delivery report e stati dei messaggi e quale ruolo svolgono nel monitoraggio delle comunicazioni SMS via API.

Quando è necessario monitorare gli SMS inviati tramite API

Un sistema che invia SMS senza monitorarne l’esito dispone di una visibilità molto limitata su ciò che accade dopo l’invio. L’applicazione sa di aver richiesto la spedizione del messaggio, ma non è in grado di verificare se il processo si sia concluso correttamente o se siano intervenuti problemi lungo il percorso.

In alcuni contesti questa mancanza di informazioni può essere accettabile. Una campagna informativa o una comunicazione non urgente possono tollerare una certa percentuale di messaggi non recapitati senza generare conseguenze operative rilevanti.

La situazione cambia quando l’SMS entra a far parte di un processo aziendale o applicativo e il suo corretto recapito influenza direttamente il funzionamento del servizio.

Alcuni esempi tipici includono:

• invio di codici OTP per autenticazione e verifica identità;
• notifiche di pagamento e conferme di transazione;
• conferme di prenotazione e appuntamento;
• alert di sicurezza;
• comunicazioni operative urgenti;
• notifiche automatiche generate da applicazioni, CRM o sistemi gestionali.

In questi scenari il monitoraggio non serve soltanto a misurare le performance della piattaforma di messaggistica. Diventa uno strumento fondamentale per governare il processo applicativo nel suo complesso.

Le informazioni restituite dai delivery report possono essere utilizzate per attivare workflow automatici, aggiornare lo stato di una pratica, generare alert interni, pianificare nuovi tentativi di invio o instradare la comunicazione verso canali alternativi come email, WhatsApp o notifiche push.

Il monitoraggio contribuisce inoltre a migliorare la qualità dei dati aziendali. Analizzando nel tempo gli esiti delle consegne è possibile individuare numerazioni non più attive, errori presenti nei database e contatti che richiedono aggiornamenti o verifiche.

Esiste infine un tema di osservabilità e controllo operativo. Quando il volume dei messaggi cresce, diventa importante poter analizzare trend di consegna, identificare anomalie, misurare i tempi di recapito e verificare il comportamento dell’infrastruttura in condizioni di carico elevato. Senza questi dati, eventuali problemi rischiano di emergere solo quando iniziano a produrre effetti visibili sugli utenti finali.

Per questo motivo le piattaforme SMS professionali non si limitano a fornire funzionalità di invio, ma mettono a disposizione strumenti di monitoraggio che consentono di seguire l’intero ciclo di vita del messaggio e integrarne le informazioni all’interno dei sistemi aziendali.

Cosa sono i Delivery Report (DLR)

Un Delivery Report (DLR) è una notifica tecnica che descrive l’esito del processo di consegna di un SMS. Rappresenta il principale meccanismo attraverso cui una piattaforma di messaggistica comunica all’applicazione ciò che è accaduto dopo l’invio del messaggio.

Quando un’applicazione invia un SMS tramite API, il messaggio attraversa diversi livelli dell’infrastruttura: viene ricevuto dal provider, instradato verso l’operatore mobile competente e infine recapitato al dispositivo del destinatario. Durante questo percorso vengono generati eventi che permettono di conoscere lo stato della consegna.

Una volta ricevuto il messaggio, l’operatore mobile restituisce al provider una serie di informazioni che descrivono l’esito dell’operazione. Queste informazioni vengono raccolte e trasformate in Delivery Report, che possono poi essere resi disponibili all’applicazione tramite API, webhook o strumenti di reporting.

Un DLR non si limita a indicare se il messaggio è stato consegnato o meno. In molti casi contiene anche informazioni aggiuntive utili per comprendere il comportamento della rete e diagnosticare eventuali problemi. Tra queste possono figurare:

• stato del messaggio;
• data e ora della consegna;
• identificativo univoco del messaggio;
• operatore destinatario;
• codici di errore o reason code;
• informazioni relative a timeout o tentativi di consegna.

Grazie a questi dati, l’applicazione può ricostruire il ciclo di vita del messaggio e prendere decisioni automatiche in base all’esito ricevuto.

Dove vengono generati i DLR

È importante sottolineare che i Delivery Report non sono generati dall’applicazione che invia il messaggio, ma dall’infrastruttura di messaggistica e dagli operatori telefonici coinvolti nel processo di consegna. Per questo motivo rappresentano la fonte più attendibile per verificare ciò che è realmente accaduto dopo l’invio.

Dal punto di vista operativo, i DLR costituiscono il principale strumento di osservabilità di una piattaforma SMS. Consentono di misurare la qualità delle consegne, individuare anomalie, analizzare eventuali errori e costruire sistemi in grado di reagire automaticamente ai diversi scenari che possono verificarsi durante la trasmissione di un messaggio.

Gli stati principali di un messaggio SMS

Una volta inviato un SMS tramite API, il messaggio attraversa diverse fasi prima di raggiungere il destinatario. Durante questo processo la piattaforma aggiorna progressivamente il suo stato, consentendo all’applicazione di seguire l’evoluzione della consegna attraverso i Delivery Report.

Le piattaforme di messaggistica possono utilizzare terminologie leggermente differenti, ma nella maggior parte dei casi gli stati disponibili descrivono tre situazioni fondamentali: messaggio in elaborazione, messaggio consegnato e messaggio non consegnato.

Fase di accettazione dell’invio

Il primo evento che l’applicazione riceve è normalmente la conferma che la richiesta è stata accettata dalla piattaforma SMS.

È importante non confondere questo passaggio con la consegna del messaggio. In questa fase il provider ha semplicemente ricevuto la richiesta, l’ha validata e l’ha inserita nel proprio flusso di elaborazione. L’SMS potrebbe non essere ancora stato instradato verso l’operatore telefonico e non esiste ancora alcuna conferma sul recapito.

Per questo motivo una risposta API positiva non può essere considerata una garanzia di consegna.

Pending

Lo stato Pending indica che il messaggio è stato preso in carico dal sistema ed è in attesa di un esito definitivo.

In questa fase il messaggio potrebbe essere già stato inoltrato all’operatore mobile, ma la piattaforma non dispone ancora di una conferma finale. Si tratta di una situazione normale e non necessariamente di un’anomalia.

Un messaggio può risultare Pending per diverse ragioni:

• il telefono del destinatario è spento;
• il dispositivo si trova fuori copertura;
• la SIM è temporaneamente non raggiungibile;
• l’operatore sta ancora tentando la consegna;
• la rete mobile non ha ancora restituito un Delivery Report conclusivo.

Lo stato Pending è particolarmente importante perché rappresenta una situazione intermedia: il messaggio non è stato consegnato, ma non può nemmeno essere considerato fallito. Le piattaforme professionali attivano generalmente meccanismi automatici di retry e continuano a tentare la consegna per un determinato periodo di tempo. Nel caso della piattaforma Esendex, un messaggio che rimane Pending oltre 72 ore viene successivamente classificato come non consegnato.

Delivered

Lo stato Delivered indica che la piattaforma ha ricevuto una conferma positiva dalla rete mobile e che il messaggio è stato correttamente recapitato.

Si tratta normalmente dello stato finale desiderato e rappresenta l’esito positivo del processo di consegna.

Oltre all’indicazione dello stato, molte piattaforme mettono a disposizione informazioni aggiuntive come data e ora della consegna, consentendo alle applicazioni di misurare tempi di recapito e qualità del servizio. Esendex prevede anche notifiche di consegna con indicazione precisa di data e ora del recapito.

Not Delivered

Lo stato Not Delivered indica che il processo di consegna si è concluso negativamente e che il messaggio non è stato recapitato al destinatario.

Le cause possono essere molteplici e non tutte dipendono dall’infrastruttura di invio. In molti casi il problema è legato alle condizioni della rete mobile o al numero destinatario.

Tra le situazioni più comuni troviamo:

• numero inesistente o non più attivo;
• SIM disattivata;
• telefono non raggiungibile per un periodo prolungato;
• blocchi applicati dall’operatore;
• errori di instradamento;
• timeout di consegna;
• problemi temporanei della rete mobile.

Perché i soli stati non bastano

Conoscere lo stato finale di un messaggio rappresenta un’informazione importante, ma spesso non è sufficiente per comprendere ciò che è realmente accaduto durante il processo di consegna.

Dal punto di vista operativo, infatti, due messaggi classificati con lo stesso stato possono corrispondere a situazioni completamente diverse tra loro.

Immaginiamo, ad esempio, due SMS che terminano entrambi con uno stato Not Delivered. Nel primo caso il destinatario potrebbe avere il telefono spento da alcune ore. Nel secondo caso il numero potrebbe non esistere più oppure essere stato disattivato definitivamente. Dal punto di vista dello stato finale il risultato è identico: il messaggio non è stato consegnato. Dal punto di vista applicativo, invece, le azioni da intraprendere sono molto diverse.

Le applicazioni moderne non si limitano infatti a registrare il successo o il fallimento di un invio. Devono interpretare il risultato per decidere come comportarsi.

Ad esempio:

• un timeout temporaneo potrebbe richiedere un nuovo tentativo di invio;
• un destinatario momentaneamente non raggiungibile potrebbe suggerire di attendere prima di effettuare un retry;
• un numero inesistente potrebbe richiedere la rimozione o la correzione del contatto nel database;
• un errore restituito dall’operatore potrebbe attivare procedure di escalation o verifiche tecniche;
• un elevato numero di errori simili potrebbe segnalare un problema più ampio a livello di rete o di configurazione.

Per questo motivo le piattaforme professionali non si limitano a fornire gli stati principali dei messaggi, ma mettono a disposizione informazioni diagnostiche molto più dettagliate.

I reason code

Tra queste rivestono un ruolo centrale i cosiddetti reason code, ovvero codici che identificano la causa specifica di una mancata consegna o di un’anomalia rilevata durante il processo di recapito.

Un reason code può indicare, ad esempio, che il numero destinatario non esiste, che il telefono è temporaneamente irraggiungibile, che la SIM è stata disattivata, che l’operatore ha applicato restrizioni particolari oppure che si è verificato un timeout durante il tentativo di consegna. Esendex, ad esempio, mette a disposizione notifiche estese che consentono di distinguere scenari differenti come Unknown Subscriber, Absent Subscriber, Call Barred, System Failure o timeout di rete.

Queste informazioni permettono di trasformare il monitoraggio da semplice attività di reporting a vero e proprio strumento di governo operativo. Le applicazioni possono utilizzare i reason code per attivare workflow automatici, migliorare la qualità dei dati, ottimizzare le strategie di retry e intervenire più rapidamente quando emergono anomalie.

In altre parole, mentre gli stati descrivono il risultato finale del processo di consegna, i reason code aiutano a comprenderne le cause. È questa combinazione di informazioni che consente di costruire sistemi di messaggistica realmente affidabili e governabili.

Come ricevere gli aggiornamenti sullo stato dei messaggi

Una volta generati i Delivery Report, l’applicazione deve poterli ricevere e utilizzare per aggiornare i propri processi interni.

Le piattaforme SMS mettono generalmente a disposizione due modalità principali per ottenere queste informazioni:

• polling delle API;
• webhook.

Entrambi gli approcci consentono di accedere agli stessi dati, ma differiscono nel modo in cui le informazioni vengono trasferite tra la piattaforma di messaggistica e l’applicazione aziendale.

Polling

Nel modello di polling è l’applicazione a interrogare periodicamente le API del provider per verificare lo stato dei messaggi inviati.

A intervalli prestabiliti il sistema esegue una richiesta verso la piattaforma SMS, recupera eventuali aggiornamenti e aggiorna i propri database o workflow.

Questo approccio presenta alcuni vantaggi:

• implementazione relativamente semplice;
• controllo diretto sulla frequenza delle interrogazioni;
• adatto a integrazioni di piccole dimensioni o a basso volume.

Esistono però anche alcuni limiti:

• genera traffico API continuo, anche quando non sono presenti aggiornamenti;
• introduce inevitabilmente un ritardo tra l’evento e la sua rilevazione;
• può diventare inefficiente quando il numero di messaggi cresce.

Per questi motivi il polling viene spesso utilizzato nelle integrazioni più semplici o quando non è possibile esporre endpoint pubblici verso l’esterno.

Webhook

Nel modello webhook il flusso viene invertito.

Invece di interrogare periodicamente le API, è la piattaforma SMS a inviare automaticamente una notifica all’applicazione ogni volta che si verifica un evento rilevante, ad esempio la consegna di un messaggio o la ricezione di un errore.

Questo approccio offre diversi vantaggi:

• aggiornamenti quasi in tempo reale;
• minore traffico API;
• migliore scalabilità;
• integrazione più naturale con workflow ed eventi applicativi.

Tra gli aspetti da considerare vi sono invece:

• la necessità di esporre endpoint HTTP accessibili dall’esterno;
• la gestione della sicurezza delle richieste in ingresso;
• la gestione di eventuali errori di consegna o ritrasmissioni delle notifiche.

Nelle integrazioni API SMS enterprise i webhook rappresentano generalmente la soluzione preferita, perché consentono di reagire rapidamente agli eventi senza introdurre interrogazioni continue verso le API.

Come funzionano i webhook SMS

In questo modello l’applicazione espone uno o più endpoint HTTP dedicati alla ricezione delle notifiche. Quando il provider riceve un aggiornamento sullo stato del messaggio — ad esempio una conferma di consegna, una mancata consegna o un cambiamento di stato — genera una richiesta HTTP verso l’endpoint configurato e trasmette le informazioni associate all’evento.

Dal punto di vista architetturale il webhook introduce un modello event-driven. L’applicazione non deve più interrogare continuamente le API per sapere se qualcosa è cambiato, ma viene informata soltanto quando si verifica un evento rilevante. Questo riduce il numero di chiamate necessarie, migliora la scalabilità dell’integrazione e consente di reagire quasi in tempo reale alle variazioni di stato dei messaggi.

Il collegamento tra l’SMS originariamente inviato e la notifica ricevuta avviene normalmente attraverso il Message ID restituito dalla piattaforma al momento dell’invio. Quando arriva il webhook, l’applicazione può utilizzare questo identificativo per individuare il messaggio corrispondente e aggiornare i propri sistemi.

Una notifica webhook contiene generalmente informazioni come:

• identificativo del messaggio;
• stato aggiornato;
• timestamp dell’evento;
• eventuali reason code;
• dettagli aggiuntivi sulla consegna.

Una volta ricevuta la notifica, l’applicazione può eseguire automaticamente le operazioni necessarie. Può aggiornare il CRM, modificare lo stato di una pratica, registrare informazioni di audit, alimentare dashboard operative oppure attivare workflow specifici in funzione dell’esito della consegna.

Nelle implementazioni enterprise i webhook vengono spesso integrati con sistemi di logging, code di messaggistica e piattaforme di monitoraggio per garantire resilienza e tracciabilità. In questo modo gli eventi generati dalla piattaforma SMS diventano parte integrante dell’ecosistema applicativo e possono essere utilizzati dagli stessi processi che governano gli altri servizi dell’organizzazione.

Come utilizzare i Delivery Report per migliorare la qualità dei dati

I Delivery Report non servono soltanto a verificare se un messaggio è stato consegnato. Nel tempo possono diventare una fonte preziosa di informazioni sulla qualità e sull’affidabilità dei dati presenti nei sistemi aziendali.

Molte organizzazioni utilizzano gli SMS per comunicare con clienti, utenti, fornitori o dipendenti attraverso dati raccolti nel corso degli anni da CRM, piattaforme e-commerce, sistemi gestionali, programmi fedeltà o applicazioni proprietarie. Con il passare del tempo, però, una parte di queste informazioni tende inevitabilmente a diventare obsoleta.

Le persone cambiano numero di telefono, disattivano SIM, commettono errori durante la registrazione oppure inseriscono dati incompleti o non corretti. Senza un meccanismo di verifica continuo, queste anomalie rimangono spesso nascoste all’interno dei database aziendali.

I Delivery Report permettono di intercettare molte di queste situazioni.

L’analisi sistematica degli esiti di consegna consente ad esempio di:

• individuare numeri non più attivi;
• rilevare errori di digitazione;
• identificare SIM dismesse;
• intercettare numerazioni non raggiungibili da lungo tempo;
• individuare anomalie ricorrenti associate a specifici segmenti di utenti;
• ridurre progressivamente gli invii inefficaci.

I Delivery Report come strumento di data quality management

Nel caso di grandi volumi di traffico, queste informazioni possono assumere un valore significativo. Un database contenente migliaia di numeri non validi genera infatti costi inutili, riduce l’efficacia delle comunicazioni e rende meno affidabili le analisi sulle performance delle campagne e dei processi di messaggistica.

Molte aziende utilizzano i dati provenienti dai Delivery Report per alimentare procedure automatiche di data quality management. Ad esempio, un numero che produce ripetutamente errori di consegna può essere segnalato per verifica, escluso temporaneamente dagli invii oppure sottoposto a processi di aggiornamento anagrafico.

In alcuni casi le informazioni provenienti dai DLR vengono integrate direttamente nei CRM e nei sistemi di customer management. Questo consente di mantenere nel tempo una visione più accurata e aggiornata dei contatti disponibili, migliorando l’efficacia delle comunicazioni future e riducendo il rischio di utilizzare dati non più validi.

Da questo punto di vista, i Delivery Report non rappresentano soltanto uno strumento di monitoraggio tecnico, ma anche una fonte continua di feedback sulla qualità delle informazioni presenti nei sistemi aziendali. Utilizzati correttamente, possono contribuire a migliorare sia l’affidabilità delle comunicazioni sia la qualità complessiva del patrimonio dati dell’organizzazione.

Conclusioni

Quando si parla di integrazione SMS, l’attenzione si concentra spesso sull’invio del messaggio. In realtà, nelle applicazioni moderne, la capacità di monitorare ciò che accade dopo l’invio è altrettanto importante.

Una risposta positiva dell’API indica soltanto che la richiesta è stata accettata dal provider. Per comprendere se il processo si sia realmente concluso con successo è necessario seguire l’intero ciclo di vita del messaggio, dalla presa in carico iniziale fino all’esito finale della consegna.

Delivery Report, stati dei messaggi, reason code e webhook permettono di ottenere questa visibilità e di trasformare la messaggistica in un componente pienamente integrato nei processi aziendali. Le informazioni raccolte possono essere utilizzate per automatizzare workflow, migliorare la qualità dei dati, gestire le eccezioni e garantire una maggiore affidabilità delle comunicazioni.

Questo aspetto diventa particolarmente importante quando gli SMS supportano attività critiche come autenticazione, sicurezza, notifiche operative o comunicazioni transazionali. In questi scenari il monitoraggio non rappresenta una funzionalità accessoria, ma una parte integrante dell’architettura applicativa.

Una corretta strategia di monitoraggio consente di individuare rapidamente anomalie, ridurre gli errori operativi e mantenere un controllo costante sul comportamento del servizio nel tempo. È proprio questa visibilità che permette di costruire integrazioni più robuste, scalabili e affidabili.

Integra il monitoraggio SMS nei tuoi sistemi con Esendex

Le API SMS di Esendex permettono di gestire l’intero ciclo di vita del messaggio, dall’invio fino alla ricezione delle notifiche di consegna. Le informazioni sullo stato dei messaggi possono essere integrate direttamente nelle applicazioni aziendali attraverso API e webhook, consentendo ai sistemi di reagire automaticamente agli eventi e mantenere una visione aggiornata delle comunicazioni in corso.

La piattaforma mette inoltre a disposizione strumenti di reportistica e monitoraggio che permettono di analizzare gli esiti delle consegne, identificare eventuali criticità e ottenere maggiore controllo sui flussi di messaggistica. Questo approccio consente di integrare gli SMS nei processi aziendali mantenendo visibilità, tracciabilità e controllo operativo.

Che si tratti di sistemi OTP, notifiche applicative, alert di sicurezza, conferme di prenotazione o comunicazioni transazionali, una corretta gestione del monitoraggio rappresenta un elemento essenziale per garantire affidabilità e continuità del servizio.

Se stai progettando un’integrazione SMS o desideri migliorare il monitoraggio delle comunicazioni già esistenti, il team Esendex può aiutarti a individuare la soluzione più adatta ai requisiti della tua organizzazione e alle caratteristiche della tua architettura applicativa.