La tua richiesta di invio può avere successo prima che il telefono del destinatario riceva qualcosa. Un report successivo dell'operatore fornisce un altro risultato, che la tua applicazione deve gestire separatamente dall'accettazione della richiesta.
Cosa mi dice una conferma di consegna?
Una conferma riporta il successo della consegna o un problema di consegna dal punto di vista della rete.
Un risultato di consegna SMS può arrivare mentre il telefono resta in un cassetto senza essere letto. Non dimostra che il destinatario abbia visto l'identità del mittente. Non stabilisce nemmeno che abbia letto il testo completo.
La rete invia le conferme separatamente dalla risposta a una richiesta di invio. Può anche sopprimere alcuni report. Il riferimento per le conferme SMPP documenta questi controlli per le connessioni con l'operatore.
Quali conferme dell'operatore espone Bird?
Ricevi eventi pubblici per gli esiti di consegna riconosciuti. Le conferme in buffer restano interne.
Una conferma in buffer indica che l'operatore sta trattenendo il messaggio. Bird la registra nel proprio log eventi interno senza modificare lo stato pubblico del messaggio. Non vedi aggiornamenti nella timeline pubblica né nei tuoi webhook.
| Stato conferma dell'operatore | Evento Bird |
|---|---|
delivered | sms.delivered |
expired | sms.expired |
rejected | sms.rejected |
delivery_failed con un motivo recuperabile | sms.undelivered |
delivery_failed con un motivo permanente o non mappato | sms.failed |
buffered | Nessun evento pubblico |
Uno stato dell'operatore non riconosciuto non produce alcun evento. L'assenza di un aggiornamento pubblico non stabilisce quindi che l'operatore non abbia inviato alcuna conferma.
Perché uno stesso stato di fallimento produce eventi diversi?
Bird usa il motivo di fallimento dell'operatore per decidere se il problema sottostante può risolversi.
| Motivo dell'operatore | Codice di errore Bird | Classificazione |
|---|---|---|
unavailable_subscriber | unreachable | Recuperabile |
received_network_error | provider_unavailable | Recuperabile |
capacity_limit_reached | provider_unavailable | Recuperabile |
unknown_subscriber | invalid_destination | Permanente |
opted_out | recipient_opted_out | Permanente |
carrier_rejected | sender_unregistered, content_rejected o blocked_by_carrier | Permanente |
Un fallimento recuperabile produce sms.undelivered. Il messaggio è comunque definitivo: Bird non riprova a inviarlo automaticamente. Per raggiungere il destinatario serve un altro invio dopo che il problema sottostante si è risolto.
Un fallimento permanente produce sms.failed.
Il SMS pumping è una frode che induce il tuo prodotto a inviare messaggi a pagamento verso numeri controllati da un attaccante. Bird segnala blocked_by_fraud_protection quando la protezione antifrode blocca un sospetto pumping.
Un motivo altrimenti non mappato produce sms.failed con il codice di errore unknown. Questo risultato significa che Bird non è riuscito a classificare il motivo dell'operatore. Non dimostra di per sé che la destinazione sia permanentemente irraggiungibile.
Posso impostare quando l'operatore smette di riprovare?
Puoi impostare una scadenza di consegna con validity_period, da 60 a 172.800 secondi (due giorni), calcolati dal momento in cui Bird accetta il messaggio.
Dopo quella scadenza, Bird non consegna più il messaggio all'operatore. Dove la rotta lo supporta, Bird trasmette all'operatore il tempo rimanente come periodo di validità del messaggio. Un codice di verifica valido per dieci minuti può impostarla a 600, così un testo che non ha raggiunto l'operatore entro dieci minuti non viene inviato.
Un messaggio che supera la scadenza prima di raggiungere l'operatore termina con rejected o failed. Bird produce sms.expired solo quando un operatore segnala la scadenza.
Ometti il campo per usare il periodo di validità del profilo di messaggistica in messaging_profile_id, oppure le regole dell'operatore quando nessuno dei due lo imposta. La risposta del messaggio riporta il valore di validity_period applicato.
Come devo gestire le conferme nella mia applicazione?
Dovresti tracciare gli esiti di consegna separatamente dall'accettazione della richiesta e da qualsiasi azione del destinatario.
Considera un messaggio senza un risultato di consegna definitivo come in sospeso. Leggi il codice di errore con un evento di fallimento per poterne indagare la causa. Conserva i codici sconosciuti nei tuoi log perché l'insieme dei codici di errore è estensibile.
Usa gli eventi di avvenuta consegna per una metrica di consegna. Per un flusso con codice di verifica o di conferma, registra il successo quando il destinatario completa l'azione. Una conferma di consegna da sola non può fornire questa misura.
Eventi SMS documenta i payload degli eventi pubblici e la timeline dei messaggi.
In breve
La consegna non stabilisce la lettura.
Una conferma riporta l'esito di consegna della rete senza confermare che una persona abbia visto il testo.
Alcune conferme non hanno un evento pubblico.
Bird registra internamente le conferme in buffer senza modificare lo stato pubblico, la timeline o il flusso webhook.
Il motivo determina l'evento di fallimento.
I motivi dell'operatore recuperabili producono sms.undelivered; i motivi permanenti o non mappati producono sms.failed.
Un motivo recuperabile non attiva un altro invio.
Un messaggio non consegnato è definitivo, quindi un altro tentativo richiede un invio separato.