Account SMPP per i clienti: bind, TPS, DLR e fatturazione

Nel momento in cui un cliente tecnico chiede “posso collegarmi in bind via SMPP?”, ai suoi occhi la Sua piattaforma smette di essere un pannello web e diventa un operatore. Gli account SMPP per i clienti sono la funzione che conquista banche, fornitori di OTP, altri aggregatori e qualsiasi sviluppatore che abbia già una libreria client SMPP, e sono anche il punto in cui una configurazione approssimativa fa più danni: un cliente senza limite di throughput, un bind receiver che nessuno ha configurato, ricevute che non arrivano da nessuna parte, un registro contabile che il bind aggira. Questa guida è la lista di controllo per fare le cose per bene, dal bind che Lei emette al test che esegue prima di dire al cliente di andare in produzione.

Che cosa sono davvero gli account SMPP per i clienti

Con l’API HTTP un cliente invia una richiesta per ogni messaggio e riceve una risposta. Con SMPP il cliente apre una sessione TCP di lunga durata verso il Suo server SMPP, si autentica una sola volta con un system_id e una password, e invia i messaggi in flusso su quella sessione come pacchetti binari chiamati PDU. La Sua piattaforma deve far girare un server SMPP (quello di Smppcube è in ascolto sulla porta 2775 ed è rappresentato nella pagina della piattaforma), accettare il bind, convalidare ogni submit_sm rispetto all’account del cliente, metterlo in coda nella stessa pipeline che alimenta l’API HTTP e, più tardi, rimandare la ricevuta di consegna lungo la sessione come deliver_sm.

Un account SMPP, quindi, non è un prodotto separato con una propria fatturazione. È una credenziale su un account cliente esistente più un insieme di limiti: quali modalità di bind, da quali IP, quante sessioni, a quale velocità. La credenziale è la parte piccola. I limiti sono l’account.

Tipi di bind e che cosa consentire

SMPP definisce tre modalità di bind, e la configurazione dell’account deve indicare quali può usare il cliente:

• Transmitter: solo invio. Il cliente invia messaggi e riceve le risposte ai submit (l’ID del messaggio), ma nient’altro. È semplice, ed è il motivo per cui le ricevute si perdono, perché un transmitter non ha alcun canale per un deliver_sm.
• Receiver: solo ricezione. Il cliente riceve le ricevute di consegna e i messaggi in entrata (le risposte inviate dai telefoni, se ne instrada verso di lui) e non può inviare.
• Transceiver: entrambe le cose su una sola sessione. È ciò che la maggior parte delle librerie client moderne apre per impostazione predefinita ed è ciò che dovrebbe consigliare, perché una sola sessione trasporta insieme invii e ricevute e non c’è nulla da disallineare.

Lo schema tradizionale con un bind transmitter più un bind receiver esiste ancora, di solito perché uno stack client più vecchio è stato scritto così. Lo consenta, ma lo conti come due sessioni rispetto al limite dell’account, e si assicuri che il bind receiver sia davvero aperto prima di dare per scontato che le ricevute vengano consegnate.

I limiti di sessione contano più di quanto si pensi. Un cliente che apre dieci bind transceiver “per ridondanza” occupa dieci posti nella tabella delle connessioni del Suo server e può spingere un throughput dieci volte superiore a quello che Lei aveva previsto. Da due a quattro sessioni per account è un valore predefinito ragionevole; un cliente che ne ha bisogno di più è un cliente che dovrebbe passare a un pacchetto superiore.

Throughput, finestre e throttling

Su SMPP il throughput dipende da due fattori: quante PDU il cliente può avere in transito prima di attendere le conferme (la finestra) e il ritmo che Lei consente. La guida SMPP contro HTTP spiega perché un singolo bind ben gestito può spingere centinaia di messaggi al secondo; il punto qui è che, sulla Sua piattaforma, è Lei a ricevere quella spinta.

Dia a ogni account SMPP un limite in messaggi al secondo che derivi dal contratto, non da ciò che il Suo server sarebbe in grado di fare. Un cliente che paga per 10 msg/s ottiene 10 msg/s; quando li supera, risponda con l’errore di throttling definito dal protocollo (ESME_RTHROTTLED) invece di mettere in coda l’eccedenza in silenzio. Una libreria client scritta bene tratta quell’errore come un invito a rallentare e riduce il ritmo. Una scritta male continua a insistere, e il Suo server dovrebbe chiudere il bind dopo violazioni ripetute e registrarne il motivo, perché l’alternativa è che il ciclo di ritentativi mal configurato di un solo cliente diventi la latenza di tutti.

Sull’account vanno altri due numeri. Una dimensione della finestra (da 10 a 20 PDU non confermate è un valore tipico per un bind rivolto ai clienti; gli operatori a monte possono consentirne di più) e un intervallo di enquire_link, l’heartbeat che tiene viva una sessione inattiva. Comunichi al cliente tutti e tre i valori quando emette le credenziali. Il ticket più comune del tipo “SMPP non funziona” nasce da una libreria client configurata per una finestra che il Suo server non concede, che va in timeout a ogni decimo messaggio e lo segnala come un guasto della piattaforma.

Dove vanno le ricevute di consegna

Una ricevuta di consegna (DLR) su SMPP non è una risposta al submit del cliente. Arriva più tardi, non sollecitata, come deliver_sm sul bind receiver o transceiver del cliente, e il cliente la abbina al messaggio originale tramite l’ID del messaggio che il Suo server ha restituito al momento del submit. Ne derivano tre conseguenze.

Primo, la ricevuta deve avere un posto dove andare. Se il cliente è collegato solo come transmitter e non ha alcun bind receiver aperto, la ricevuta non ha un percorso. Decida la politica in anticipo: richiedere bind transceiver, trattenere le ricevute per un breve periodo finché non compare un bind receiver, oppure offrire un webhook come canale delle ricevute ai clienti che non possono gestire un receiver. Scartare le ricevute in silenzio è l’unica opzione che Le tornerà indietro sotto forma di contestazione.

Secondo, la ricevuta è Sua prima di essere del cliente. La Sua piattaforma ha bisogno della ricevuta dell’operatore per chiudere il messaggio nel registro contabile, per mostrare lo stato nella console del cliente e per alimentare la Sua reportistica sulla qualità di consegna per rotta. La memorizzi, aggiorni il messaggio e solo dopo la inoltri. Un progetto che si limita a inoltrare le ricevute al bind senza conservare nulla è un progetto senza risposta quando il cliente dice “mi avete addebitato 4.000 messaggi che non sono mai arrivati”.

Terzo, le ricevute arrivano più o meno al ritmo degli invii, e quelle di una campagna arrivano dopo la campagna. Un cliente che lancia 50.000 messaggi in cinque minuti riceverà 50.000 pacchetti deliver_sm nei dieci minuti successivi. Se il suo bind receiver è lento a confermare, la Sua coda di ricevute in uscita cresce: ne faccia una coda con una profondità visibile anziché un buffer illimitato, e imposti avvisi sull’anzianità, così che un bind cliente bloccato compaia sulla Sua dashboard prima che il cliente apra un ticket.

Sender ID, codifica e gli errori tipici dei clienti

Un account SMPP ha bisogno anche di un regolamento. Quali indirizzi di origine (sender ID) può usare il cliente, alfanumerici o numerici, e il Suo server riscrive o rifiuta quelli sconosciuti? Quali codifiche dei dati (GSM 7-bit oppure UCS-2 per gli alfabeti non latini), e come vengono suddivisi i messaggi lunghi (concatenazione UDH, che di solito la libreria del cliente gestisce, ma non sempre)? Quale periodo di validità e quale flag di registered delivery richiede, perché le ricevute vengano effettivamente richieste?

Queste regole devono stare sull’account ed essere applicate al momento del submit, restituendo un codice di errore chiaro, invece di essere accettate per poi fallire in silenzio presso l’operatore. Così come una buona API HTTP restituisce un 400 con una motivazione, un buon server SMPP rifiuta il submit_sm con lo stato corretto e lascia che il cliente corregga la configurazione dalla sua parte. Ogni regola applicata al Suo ingresso è una contestazione che non dovrà affrontare più avanti.

Fatturazione per bind: il registro appartiene all’account

Questa è la parte che va storta quando il server SMPP viene affiancato alla piattaforma invece di essere integrato in essa. Un messaggio che entra via SMPP deve essere tariffato e addebitato esattamente come un messaggio che entra dalla console o dall’API HTTP: stesso piano tariffario, stesso saldo, stesso margine registrato sulla stessa rotta. Le tre modalità di fatturazione della guida alla fatturazione (CreditRoute, WalletRoute e AutoRoute) si applicano all’account, e il bind le eredita. Quando il saldo arriva a zero, il server SMPP deve rifiutare il submit con un errore appropriato invece di accettare traffico in una coda che non verrà mai pagata.

Un bind SMPP è una porta d’accesso all’account del cliente, non un account separato. Se il registro contabile non vede la porta, la porta è una falla.

Dove SMPP si guadagna una propria voce commerciale è nel pacchetto attorno al bind: un impegno minimo mensile in cambio di un limite di throughput più alto, un canone per ogni sessione aggiuntiva, un sovrapprezzo per una rotta dedicata o per uno short code. Li tariffi come condizioni dell’account, così che il registro riporti il canone e il traffico sullo stesso estratto conto, e così che un cliente che passa da HTTP a SMPP veda un’unica fattura con una riga in più, non un nuovo rapporto commerciale.

Attivare un cliente: il pacchetto delle credenziali

Quando un cliente viene approvato per SMPP, invii un solo documento, e che sia ogni volta lo stesso:

1. Host, porta e le indicazioni su TLS, se termina TLS davanti al server SMPP.
2. system_id e password (consegnati tramite un canale diverso dall’e-mail che contiene il resto).
3. Modalità di bind consentite e numero massimo di sessioni.
4. Gli indirizzi IP da cui accetterà i bind, e come modificarli.
5. Limite di throughput in msg/s, dimensione della finestra, intervallo di enquire_link.
6. Sender ID consentiti, regole di codifica, gestione dei messaggi lunghi, flag di registered delivery richiesto.
7. Dove vanno le ricevute, e i codici di errore che il cliente deve aspettarsi e gestire.
8. La rotta di test e i numeri di test da usare prima dell’avvio in produzione.

Metà di questi dati sono numeri che l’ingegnere del cliente inserirà in un file di configurazione entro la prossima ora. Fornirli tutti insieme fa la differenza tra un’integrazione di un giorno e uno scambio di e-mail lungo due settimane.

Test prima dell’avvio in produzione

Non attivi mai l’account SMPP di un cliente sulle rotte reali. Metta a disposizione una rotta di test che accetti i messaggi, generi una ricevuta plausibile dopo un breve ritardo e non addebiti nulla, e accompagni il cliente in sei verifiche su di essa: un bind in ciascuna modalità consentita; un singolo messaggio e la sua ricevuta, abbinata tramite ID; un messaggio lungo in un alfabeto non latino che arriva come un unico messaggio su un telefono reale; una raffica oltre il limite di throughput che produce errori di throttling e una corretta riduzione del ritmo; un sender ID volutamente errato che produce il rifiuto previsto; una connessione interrotta seguita da una riconnessione pulita. Solo allora passi l’account alle rotte reali, e lo faccia con il limite ancora attivo.

La stessa rotta di test è quella che userà più avanti per riprodurre un problema segnalato da un cliente. Un cliente che dice “le ricevute si sono fermate” può collegarsi in bind alla rotta di test, inviare un messaggio e vedere la ricevuta tornare nella console, e così un ticket vago diventa un controllo di dieci minuti sul suo bind receiver.

Quando un cliente non dovrebbe avere SMPP

Non tutti i clienti che chiedono SMPP dovrebbero ottenerlo. Un team marketing che invia da un browser non ha alcun bisogno di un bind; uno sviluppatore che invia 300 OTP al giorno è servito meglio dall’API HTTP, che non richiede una sessione persistente e restituisce errori leggibili. SMPP è per i clienti con volumi importanti, con uno stack SMPP già esistente o con un motivo di conformità per mantenere un rapporto diretto a livello di protocollo. Tutti gli altri ricevono l’API, e la Sua coda di assistenza ne esce più leggera.

Ciò che rende credibile l’offerta è che sotto c’è la stessa piattaforma, e con una licenza self-hosted il server SMPP è incluso invece di essere venduto come livello separato. Un cliente che parte dall’API HTTP e cresce fino a un bind SMPP conserva il suo account, il suo saldo, il suo piano tariffario e la sua reportistica; il bind è solo un canale in più verso un account omnicanale che può trasportare anche il suo traffico WhatsApp e RCS sullo stesso registro contabile. Questa continuità è ciò che un rivenditore che affitta un pannello di solito non può offrire, ed è il motivo, poco appariscente, per cui i clienti tecnici restano.