UC-004 — Verifica Stato di Consegna

Campo	Valore
ID	UC-004
Obiettivo	Verificare lo stato di consegna dei messaggi con polling e webhook
Canale	Multi-canale (SMS, RCS, WhatsApp)
Complessità	Base
Tempo stimato	15 minuti
API coinvolte	`GET /api/partner-gateway/v1/messages/status/{customerMessageId}`, `GET /api/partner-gateway/v1/messages/status`

Scenari reali

Dashboard OTP — Verifica invii: BancaSicura monitora in tempo reale se i codici OTP vengono consegnati entro 5 secondi, attivando un canale alternativo in caso di fallimento.
Report consegna campagna: MarketingPro genera un report di fine campagna SMS con percentuali di consegna, errori e tempi medi.
Monitoring real-time: TechStore integra lo status check nel proprio CRM per mostrare un badge "Consegnato" o "In attesa" accanto a ogni comunicazione inviata.

Polling vs Webhook

Caratteristica	Polling	Webhook
Direzione	Il tuo server chiama l'API	L'API chiama il tuo server
Latenza	Dipende dall'intervallo di polling	Tempo reale
Carico API	Proporzionale al numero di chiamate	Una chiamata per evento
Complessità	Bassa (basta un loop)	Media (serve endpoint pubblico)
Ideale per	Verifiche puntuali, debug, piccoli volumi	Produzione, alti volumi, real-time

:::tip Quale scegliere? Usa il polling per test, debug e verifiche manuali. Usa i webhook in produzione per ricevere notifiche in tempo reale senza sovraccaricare l'API. Vedi la guida Webhook per la configurazione. :::

Step 1 — Invia un messaggio (prerequisito)

Per verificare lo stato, devi prima aver inviato un messaggio e aver salvato il messageId. Esempio rapido con SMS:

curl -s -X POST https://lora-api.agiletelecom.com/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "BancaSicura",
    "body": "Il tuo codice OTP e: 847293. Valido per 5 minuti.",
    "enableNotification": true
  }'

Response

{
  "messageId": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Dietro le quinte — Timeline degli stati

Dopo l'invio, il messaggio attraversa questi stati in sequenza:

SENT — Il gateway ha accettato il messaggio e lo ha inoltrato all'operatore.
DELIVERED — L'operatore conferma la consegna al dispositivo del destinatario.
READ (solo RCS/WhatsApp) — Il destinatario ha aperto e visualizzato il messaggio.
ERROR — L'operatore segnala un errore di consegna.
EXPIRED — Il messaggio non e stato consegnato entro il TTL (Time To Live).

La transizione SENT -> DELIVERED avviene tipicamente in 1-5 secondi per SMS, 0.5-2 secondi per RCS/WhatsApp.

Step 2 — Polling singolo

Interroga lo stato di un singolo messaggio usando il messageId come path parameter e il channel come query parameter.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status/d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890?channel=SMS" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — DELIVERED

{
  "customerMessageId": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
  "channel": "SMS",
  "destination": "+393471234567",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusDescription": "Message delivered to handset",
  "sendDate": "2026-04-09T15:00:00+02:00",
  "deliveryDate": "2026-04-09T15:00:03+02:00",
  "readDate": null
}

Response — ERROR

{
  "customerMessageId": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
  "channel": "SMS",
  "destination": "+393471234567",
  "deliveryStatus": "ERROR",
  "deliveryStatusDescription": "Undeliverable",
  "sendDate": "2026-04-09T15:00:00+02:00",
  "deliveryDate": null,
  "readDate": null
}

Dietro le quinte — Tabella completa degli status

Status	Codice webhook	Canale	Descrizione
`DELIVERED`	3	SMS, RCS, WhatsApp	Messaggio consegnato con successo
`SENT`	—	Tutti	Messaggio inviato, in attesa di conferma dall'operatore
`RECEIVED`	—	RCS, WhatsApp	Messaggio ricevuto dal server WhatsApp/RCS
`ERROR`	6	Tutti	Errore di consegna (numero inesistente, rete irraggiungibile)
`EXPIRED`	8	Tutti	TTL scaduto, il messaggio non e stato consegnato in tempo
`UNKNOWN`	—	Tutti	Stato non ancora determinato

Note sui codici webhook: I statusCode numerici (3, 6, 8) sono usati nei callback webhook. Nell'API di status polling, il campo deliveryStatus e una stringa leggibile.

Step 3 — Polling batch

Per verificare lo stato di più messaggi in una sola chiamata, usa l'endpoint batch. Tutti gli ID devono appartenere allo stesso canale.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status?channel=SMS&ids=d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890,a1b2c3d4-e5f6-7890-abcd-ef1234567890,f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Batch status

[
  {
    "customerMessageId": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
    "channel": "SMS",
    "destination": "+393471234567",
    "deliveryStatus": "DELIVERED",
    "deliveryStatusDescription": "Message delivered",
    "sendDate": "2026-04-09T15:00:00+02:00",
    "deliveryDate": "2026-04-09T15:00:03+02:00",
    "readDate": null
  },
  {
    "customerMessageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "channel": "SMS",
    "destination": "+393481234567",
    "deliveryStatus": "DELIVERED",
    "deliveryStatusDescription": "Message delivered",
    "sendDate": "2026-04-09T15:00:01+02:00",
    "deliveryDate": "2026-04-09T15:00:04+02:00",
    "readDate": null
  },
  {
    "customerMessageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "channel": "SMS",
    "destination": "+393491234567",
    "deliveryStatus": "ERROR",
    "deliveryStatusDescription": "Undeliverable",
    "sendDate": "2026-04-09T15:00:01+02:00",
    "deliveryDate": null,
    "readDate": null
  }
]

:::note ID non trovati Gli ID che non corrispondono a nessun messaggio vengono silenziosamente omessi dalla response. Se invii 3 ID e ricevi solo 2 risultati, il terzo non e stato trovato. :::

Dietro le quinte — Limiti e best practice del batch

Limite ID: Puoi inviare fino a diverse centinaia di ID in una singola chiamata. Per volumi superiori, suddividi in più richieste.
Stesso canale: Tutti gli ID devono appartenere allo stesso canale (SMS, RCS o WHATSAPP). Per canali misti, esegui chiamate separate.
Ordine risultati: I risultati non sono ordinati. Usa customerMessageId per fare il match con i tuoi record.
Polling interval: Per verifiche automatiche, usa un intervallo di almeno 5 secondi tra una chiamata e l'altra. Per volumi elevati, passa ai webhook.

Esempio: polling loop con retry

Uno script bash che verifica lo stato ogni 3 secondi, con timeout di 30 secondi:

#!/bin/bash
MESSAGE_ID="d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890"
API_KEY="YOUR_API_KEY"
MAX_ATTEMPTS=10
ATTEMPT=0

while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
  ATTEMPT=$((ATTEMPT + 1))
  echo "Tentativo $ATTEMPT/$MAX_ATTEMPTS..."

  STATUS=$(curl -s -X GET \
    "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status/${MESSAGE_ID}?channel=SMS" \
    -H "X-Api-Key: ${API_KEY}" | jq -r '.deliveryStatus')

  echo "Status: $STATUS"

  if [ "$STATUS" = "DELIVERED" ]; then
    echo "Messaggio consegnato!"
    exit 0
  elif [ "$STATUS" = "ERROR" ] || [ "$STATUS" = "EXPIRED" ]; then
    echo "Errore di consegna: $STATUS"
    exit 1
  fi

  sleep 3
done

echo "Timeout: stato finale non raggiunto"
exit 2

Confronto canali

Campo	SMS	RCS	WhatsApp
`deliveryStatus`	DELIVERED, SENT, ERROR, EXPIRED	DELIVERED, SENT, ERROR, EXPIRED	DELIVERED, SENT, RECEIVED, ERROR, EXPIRED
`readDate`	Sempre `null`	Presente se letto	Presente se letto
Latenza tipica DELIVERED	1-5 secondi	0.5-2 secondi	0.5-2 secondi
Webhook READ	Non disponibile	Disponibile	Disponibile

Errori comuni

404 — Messaggio non trovato

{}

Soluzione: Verifica che il customerMessageId sia corretto e che il parametro channel corrisponda al canale usato per l'invio. I messaggi molto vecchi potrebbero non essere più disponibili.

Canale errato nel parametro channel

Se invii un messaggio via SMS ma interroghi lo stato con channel=RCS, riceverai un 404 anche se il messaggio esiste. Assicurati che il canale nella query corrisponda a quello usato nell'invio.

Status UNKNOWN persistente

Se lo status resta UNKNOWN per più di 60 secondi, potrebbe indicare un problema di routing. Verifica:

Il numero del destinatario e valido e raggiungibile
L'operatore del destinatario e supportato
Non ci sono problemi di rete in corso

Risultato atteso

Step	Azione	Risultato
1	`POST /sms/send` (o RCS/WhatsApp)	`messageId` salvato
2	`GET /messages/status/{id}?channel=SMS`	`deliveryStatus: "DELIVERED"`
3	`GET /messages/status?channel=SMS&ids=id1,id2,id3`	Array di status per ogni messaggio

Prossimi passi

UC-001 — Invio SMS Singolo: Scenario completo di invio e verifica SMS
UC-002 — Invio RCS Rich Card: Rich card con conferma di lettura
UC-003 — Invio WhatsApp Template: Template con status tracking
Guida Webhook: Configura i webhook per notifiche real-time
Guida Autenticazione: Setup API Key e Basic Auth

Scenari reali​

Polling vs Webhook​

Step 1 — Invia un messaggio (prerequisito)​

Response​

Step 2 — Polling singolo​

Response — DELIVERED​

Response — ERROR​

Step 3 — Polling batch​

Response — Batch status​

Esempio: polling loop con retry​

Confronto canali​

Errori comuni​

404 — Messaggio non trovato​

Canale errato nel parametro channel​

Status UNKNOWN persistente​

Risultato atteso​

Prossimi passi​