Message Delivery Status

Controlla lo stato di consegna di uno o più messaggi inviati.

📄️Ottieni lo stato di consegna di più messaggi

Restituisce lo stato di consegna di più messaggi in una singola chiamata, il che è molto più efficiente che chiamare in un ciclo l'endpoint di stato singolo. Tutti gli ID forniti in una singola richiesta devono appartenere allo stesso canale (SMS, RCS o WHATSAPP). Se devi controllare messaggi su canali diversi, effettua una richiesta batch per canale. Fornisci i valori customerMessageId come stringa separata da virgole nel parametro query ids (ad esempio: ids=msg-001,msg-002,msg-003). Non includere spazi tra gli ID. Anche se non esiste un limite rigido al numero di ID, si consiglia di mantenere ogni batch sotto qualche centinaio di ID, per evitare query string eccessivamente lunghe e possibili errori HTTP 414 URI Too Long da parte di proxy o load balancer intermedi. Per ricerche molto grandi, suddividi gli ID in più richieste. La risposta è una lista non ordinata di oggetti DeliveryStatusResponse. Importante: gli ID che non corrispondono ad alcun messaggio noto per l'azienda autenticata e il canale specificato vengono omessi silenziosamente dai risultati. Ciò significa che l'array di risposta può contenere meno elementi del numero di ID che hai fornito. Se nessuno degli ID corrisponde, riceverai un array vuoto (HTTP 200 con una lista JSON vuota), non un 404. Per individuare i messaggi mancanti, confronta i valori customerMessageId restituiti con la tua lista originale. Ogni voce della risposta contiene gli stessi campi dell'endpoint di stato singolo, inclusi deliveryStatus (ACCEPTED, REJECTED, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ERROR, DISABLED, UNSUPPORTED, CONVERSATION_CLOSED, UNKNOWN — vedi la tabella Stati di Consegna nella panoramica dell'API) e deliveryStatusDescription per i dettagli in forma leggibile. Risposte di errore: viene restituito 400 quando channel o ids mancano, o quando channel non è uno tra RCS, WHATSAPP, SMS. 500 indica un errore imprevisto lato server; riprova la richiesta dopo una breve attesa. Per la ricerca di un singolo messaggio, usa invece GET /partner-gateway/v1/messages/status/{customerMessageId}. Per una vista storica completa con paginazione e filtro per data, consulta GET /partner-gateway/v1/messages/history.

📄️Ottieni lo stato di consegna di un singolo messaggio

Restituisce lo stato di consegna attuale di un singolo messaggio identificato dal suo customerMessageId. Il customerMessageId è l'identificatore univoco che la piattaforma assegna al tuo messaggio quando lo invii tramite uno degli endpoint di invio (POST /partner-gateway/v1/sms/messages, POST /partner-gateway/v1/rcs/messages o POST /partner-gateway/v1/whatsapp/messages). Dovresti memorizzare questo identificatore dalla tua parte subito dopo una chiamata di invio riuscita, così da poter monitorare il ciclo di vita del messaggio in seguito. Flusso di lavoro tipico: (1) Invia un messaggio tramite l'endpoint del canale appropriato e ricevi il customerMessageId nella risposta. (2) Attendi un tempo ragionevole per l'elaborazione da parte del carrier (pochi secondi per gli SMS, potenzialmente di più per RCS e WhatsApp). (3) Chiama questo endpoint con il customerMessageId e il canale corrispondente per ottenere lo stato attuale. Il parametro query channel è obbligatorio e deve corrispondere esattamente al canale usato per inviare il messaggio. Fornire un canale non corrispondente (ad esempio, interrogare un messaggio SMS con channel=RCS) restituirà un 404, perché la ricerca è limitata al canale specificato. Stati di consegna possibili e relativi significati: ACCEPTED (SMS) - il messaggio è stato accettato dalla piattaforma e inoltrato al carrier, ma non è ancora tornata alcuna ricevuta di consegna. È lo stato di un SMS mentre è in transito. DELIVERED - il carrier o il provider del canale ha confermato che il messaggio ha raggiunto il dispositivo del destinatario. REJECTED (SMS) - il carrier ha rifiutato il messaggio. UNDELIVERABLE (SMS) - la destinazione non può ricevere il messaggio, in genere perché il numero è irraggiungibile o non valido. DELETED (SMS) - il messaggio è stato annullato prima di poter essere consegnato. EXPIRED - il messaggio non è stato consegnato entro la finestra time-to-live consentita e il carrier lo ha scartato. ERROR (RCS, WhatsApp) - il messaggio non è stato consegnato; controlla il campo deliveryStatusDescription per il motivo specifico (le cause comuni includono numero di destinazione non valido, rifiuto da parte del carrier o sospensione dell'account). DISABLED (RCS, WhatsApp) - il destinatario ha il canale disattivato. UNSUPPORTED (RCS, WhatsApp) - il dispositivo o il numero del destinatario non supporta il canale. CONVERSATION_CLOSED (WhatsApp) - la finestra di assistenza clienti di 24 ore si era chiusa. UNKNOWN - la piattaforma non ha informazioni di stato per questo messaggio; su RCS e WhatsApp questo copre anche un messaggio ancora in attesa della prima ricevuta, poiché quei canali non hanno un codice proprio per i messaggi in transito. La tabella Stati di Consegna nella panoramica dell'API elenca il codice numerico che il webhook di consegna invia per ciascuno di questi stati. Risposte di errore: viene restituito 400 quando il parametro channel manca o non è uno tra RCS, WHATSAPP, SMS. Viene restituito 404 quando il customerMessageId non esiste per il canale e l'azienda indicati, o quando il parametro channel non corrisponde al canale di invio originale. 500 indica un errore imprevisto lato server; riprova la richiesta dopo una breve attesa. Per controlli di stato in blocco, usa invece l'endpoint batch GET /partner-gateway/v1/messages/status.