API SMS o SMPP: quale connessione scegliere per i vostri SMS

Questa guida è pensata per ingegneri e responsabili tecnici che devono decidere come collegarsi a un provider SMS: tramite una API SMS HTTP/REST, tramite SMPP o con entrambe. Spiega come le due soluzioni differiscono davvero a livello di protocollo e di operatività, così potete scegliere l'interfaccia giusta per ogni tipo di traffico e pianificare una migrazione se la prima scelta non basta più.

Per una visione più ampia dei modelli di integrazione, compresi webhook e idempotenza, vedi la nostra guida all'integrazione delle API di messaggistica.

Qual è la differenza tra una API SMS e SMPP?

Una API SMS REST invia ogni messaggio come richiesta HTTPS separata e restituisce un ID messaggio. SMPP (Short Message Peer-to-Peer) mantiene aperta una sessione autenticata di lunga durata e scambia al suo interno messaggi binari, detti PDU, in entrambe le direzioni. REST ottimizza la semplicità; SMPP ottimizza il volume SMS sostenuto.

Come funziona una API SMS REST?

Effettuate una POST HTTPS con un token e un corpo JSON, e il provider risponde con un ID. Ogni richiesta è indipendente, quindi potete inviare da qualsiasi server, funzione o container senza gestire una connessione.

Un invio tipico con la nostra API si presenta così:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "971500000000",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

La risposta è 200 OK con l'ID del messaggio come testo semplice. Lo stato finale arriva in seguito al vostro webhook come SUBMITTED, SENT, DELIVERED, FAILED o REJECTED. Nomi dei campi e opzioni sono nel riferimento dell'API SMS.

I punti di forza di REST:

• Strumenti familiari: qualsiasi linguaggio, qualsiasi client HTTP, codici di stato standard come definiti nell'RFC 9110.
• Sicurezza semplice: TLS ovunque e un token nell'header Authorization.
• Invio massivo senza connessioni: caricate un file di destinatari in una sola richiesta invece di aprire una sessione.
• Una sola API per più canali: lo stesso schema invia template WhatsApp o card RCS.

I limiti di REST: ogni messaggio, o ogni batch, costa un round trip HTTP e incontrerete un limite di richieste al secondo prima di incontrare qualsiasi limite dell'operatore. Per la maggior parte del traffico applicativo questo non ha mai importanza.

Come funziona SMPP?

SMPP è un protocollo binario definito dalla specifica SMPP v3.4, pubblicata dallo SMPP Developers Forum (poi SMS Forum) e ancora la versione più diffusa. Il vostro sistema, detto ESME (External Short Message Entity), si connette all'SMSC (Short Message Service Centre) del provider e apre una sessione chiamata bind.

Tipi di bind

• Transmitter (TX), con bind_transmitter: solo invio di messaggi.
• Receiver (RX), con bind_receiver: solo ricezione di rapporti di consegna e messaggi in entrata.
• Transceiver (TRX), con bind_transceiver: entrambe le funzioni su una sola sessione. È la scelta abituale.

Ciclo di vita della sessione

1. Aprite una connessione TLS verso host e porta indicati dal provider.
2. Inviate bind_transceiver con system_id e password e attendete una risposta con command_status 0.
3. Inviate i messaggi con submit_sm. Ogni submit_sm_resp restituisce un message_id.
4. Ricevete i rapporti di consegna come deliver_sm e rispondete a ciascuno con deliver_sm_resp.
5. Inviate periodicamente enquire_link quando la sessione è inattiva, così entrambe le parti sanno che è viva.
6. Chiudete con unbind e attendete unbind_resp.

Ogni PDU porta un numero di sequenza e le risposte portano lo stesso numero: è così che associate una submit_sm_resp al messaggio inviato. La nostra documentazione SMPP illustra ogni passaggio con le nostre impostazioni.

Che cos'è il windowing SMPP e perché conta?

Windowing significa inviare più PDU submit_sm prima che ne tornino le risposte. Il numero di PDU senza conferma consentite in volo è la finestra. È il motivo principale per cui SMPP sostiene un throughput maggiore di HTTP a richiesta singola.

Con una finestra di 1, il client invia un messaggio, attende un intero round trip per la risposta, poi invia il successivo. Il throughput è limitato dalla latenza di rete, non dalla velocità concordata. Con una finestra più ampia, la connessione resta occupata mentre arrivano le risposte.

Regole pratiche:

• Usate la dimensione di finestra concordata con il provider e non superatela mai; le PDU in eccesso possono essere rifiutate.
• Rispettate la velocità concordata per bind. Se ricevete ESME_RTHROTTLED, rallentate e riprovate con backoff.
• Tenete traccia dei numeri di sequenza in sospeso, così una disconnessione non vi fa perdere il conto dei messaggi accettati.
• Scalate con più bind, fino al numero concordato per il vostro account, invece che con una finestra sempre più ampia.

I limiti predefiniti della nostra API REST e dei bind SMPP sono elencati in errori e limiti; i limiti del vostro account vengono confermati al momento dell'attivazione dell'accesso.

In cosa differiscono i rapporti di consegna?

Con REST, il provider invia un evento JSON al vostro webhook. Con SMPP, il rapporto arriva come PDU deliver_sm sulla sessione, con il bit del rapporto impostato in esm_class. Entrambi sono asincroni; né 200 OK né submit_sm_resp significano che il telefono abbia ricevuto il messaggio.

La specifica SMPP v3.4 indica il formato testuale del rapporto come esempio e lascia il formato esatto al fornitore dell'SMSC, ma la maggior parte dei provider lo segue:

id:2603121407537573731 sub:001 dlvrd:001 submit date:2610100914 done date:2610100915 stat:DELIVRD err:000 text:Your OmniDemo code

Se i vostri sistemi usano entrambe le interfacce, mappate gli stati SMPP su un unico modello di stato. Una mappatura tipica:

Due differenze pratiche contano più del formato:

• Conferma. Un client SMPP deve rispondere a ogni deliver_sm. I rapporti non confermati vengono reinviati e possono rallentare il bind. Per lo stesso motivo un gestore di webhook deve rispondere 2xx rapidamente.
• Ripristino. Se il client SMPP si disconnette, i rapporti restano in attesa del bind successivo o possono scadere nella coda del provider. Con REST, un provider può offrire il rinvio dei rapporti per un intervallo di date. Chiedete come funziona ciascuno.

Per saperne di più sul significato di ogni stato, leggi gli stati di consegna dei messaggi spiegati.

Come viene gestita la codifica?

Entrambe le interfacce devono scegliere tra GSM-7 e Unicode ed entrambe dividono i messaggi lunghi in segmenti. La differenza è chi fa il lavoro.

• REST: impostate un campo come messageType su TEXT o UNICODE e la piattaforma segmenta i messaggi lunghi. La nostra API dispone anche di POST /sms/identify per contare prima caratteri e segmenti.
• SMPP: impostate data_coding (0 per l'alfabeto predefinito GSM-7, 8 per UCS-2) e codificate voi stessi i byte. Per i messaggi lunghi, aggiungete uno User Data Header a ogni parte e impostate esm_class a 0x40, oppure inviate l'intero testo nel campo message_payload se il provider lo abilita.

Secondo 3GPP TS 23.040, un singolo SMS contiene 140 ottetti: 160 caratteri GSM-7 o 70 caratteri UCS-2, che scendono a 153 o 67 per parte quando si aggiunge l'header. Una sola lettera araba o una emoji rende Unicode l'intero messaggio. I bug di codifica sono il difetto di integrazione SMPP più comune, quindi testate con arabo, emoji e testi lunghi. Vedi la nostra guida ai limiti di caratteri.

Come si confrontano i modelli di sicurezza?

REST si basa su TLS e su un bearer token per ogni richiesta. SMPP v3.4 non ha una propria cifratura e invia le credenziali nel bind, quindi dipende dal trasporto e dai controlli di rete che lo circondano.

Per SMPP:

• Usate TLS (TLS 1.3 è definito nell'RFC 8446) o un collegamento privato; mai SMPP in chiaro su Internet pubblico.
• Registrate gli indirizzi IP di origine, così solo i vostri server possono effettuare il bind.
• Conservate system_id e password come segreti, distinti per ambiente, e ruotateli se esposti.
• Monitorate i fallimenti di bind, che possono segnalare errori di configurazione o uso improprio delle credenziali.

Per REST:

• Tenete il token solo sui server, mai in app mobili o nel codice del browser.
• Evitate le interfacce HTTP legacy che passano nome utente e password nell'URL, dove finiscono nei log.
• Proteggete il webhook con HTTPS, un percorso non indovinabile e una rigorosa validazione del corpo.

Quanto costa gestire ciascuna opzione?

REST aggiunge un onere operativo quasi nullo: le richieste hanno successo oppure restituiscono un errore che potete ritentare. SMPP aggiunge un componente sempre in esecuzione da monitorare e mantenere.

Un client SMPP richiede:

1. gestione delle connessioni, con riconnessione tramite backoff e jitter invece di un ciclo serrato;
2. keep-alive e rilevamento delle connessioni silenziose e semi-aperte;
3. controllo di finestra e velocità per ogni bind;
4. tracciamento delle sequenze e riconciliazione dopo le disconnessioni;
5. conferma e archiviazione dei rapporti;
6. logica di codifica e concatenazione;
7. monitoraggio di stato dei bind, throughput, errori di throttling e ritardo dei rapporti.

Le librerie open source mature gestiscono il protocollo, ma il vostro team è comunque responsabile di ciò che le circonda, anche durante una finestra di manutenzione del provider alle 3 di notte.

Quando usare l'una o l'altra?

Usate REST a meno che non abbiate un motivo chiaro per aggiungere SMPP.

Scegliete una API SMS REST quando

• inviate OTP, avvisi, notifiche o campagne da applicazioni;
• vi servono WhatsApp, RCS o altri canali oltre agli SMS;
• la vostra piattaforma gira su funzioni serverless o container di breve durata;
• il vostro team non ha esperienza di SMPP né necessità di svilupparla.

Scegliete SMPP quando

• inviate volumi SMS elevati e costanti e avete raggiunto i limiti di REST;
• avete già un gateway SMPP o una piattaforma di messaggistica;
• siete un aggregatore, un operatore o un rivenditore che collega il traffico SMS dei propri clienti;
• vi serve lo stesso protocollo verso più provider a monte.

Come si presenta una configurazione ibrida?

Molte aziende usano entrambe sullo stesso account: REST per il traffico multicanale e applicativo, SMPP per gli SMS massivi. La trappola è ritrovarsi con due modelli di consegna.

• Instradate per caso d'uso, non a caso: ad esempio OTP e WhatsApp su REST, estratti conto in SMS massivi su SMPP.
• Normalizzate gli stati di webhook e deliver_sm in un'unica tabella con chiave sull'ID del messaggio.
• Usate un'unica policy sui Sender ID per entrambe, poiché le registrazioni valgono qualunque interfaccia usiate.
• Create report unificati, così una campagna divisa tra le due interfacce mostra un unico risultato.

Come si migra da una API SMS a SMPP?

Procedete gradualmente, con entrambe le interfacce attive, e misurate prima di spostare i volumi.

1. Confermate la necessità: documentate il volume o il throughput che REST non soddisfa.
2. Richiedete il provisioning: condividete paesi di destinazione, Sender ID, picco di throughput previsto e indirizzi IP di origine.
3. Scegliete una libreria client matura per il vostro stack e racchiudetela in una vostra interfaccia di invio.
4. Sviluppate prima la gestione dei rapporti, mappata sullo stesso modello di stato dei webhook.
5. Testate la codifica: GSM-7, arabo, emoji e messaggi in più parti su telefoni reali.
6. Testate i guasti: interrompete la connessione durante l'invio, provocate il throttling e verificate la riconciliazione.
7. Eseguite in parallelo: spostate su SMPP una piccola quota di un tipo di traffico e confrontate consegna e rapporti.
8. Spostate i volumi per gradi, mantenendo REST come percorso di riserva.

Una configurazione di bind a titolo illustrativo si presenta così. Host, porta e limiti sono segnaposto; i valori reali arrivano con le credenziali attivate.

host:                 <provided with your bind>
port:                 <TLS port provided with your bind>
bind type:            transceiver
system_id:            <your system_id>
password:             <your password>
system_type:          (empty unless told otherwise)
interface_version:    0x34
source_addr_ton/npi:  5 / 0   (alphanumeric sender ID)
dest_addr_ton/npi:    1 / 1   (international number)
registered_delivery:  1       (request delivery receipts)
data_coding:          0 (GSM-7) or 8 (UCS-2)
enquire_link:         every 30 seconds while idle
window:               as agreed for your account

Esempio pratico: un rivenditore regionale aggiunge SMPP per gli estratti conto

"Souq Rafiq" (nome di fantasia), un rivenditore online negli Emirati Arabi Uniti, in Egitto e in Giordania, invia OTP e aggiornamenti sugli ordini tramite una API REST e template WhatsApp tramite la stessa API. Gli estratti conto mensili, inviati via SMS a tutta la base clienti, sono cresciuti al punto che il job REST impiega più tempo di quanto l'azienda voglia.

• Decisione: mantenere OTP, aggiornamenti sugli ordini e WhatsApp su REST. Spostare gli SMS degli estratti conto mensili su un bind SMPP transceiver.
• Provisioning: il team registra due IP di origine, conferma i Sender ID per paese e concorda throughput e numero di bind.
• Sviluppo: un piccolo servizio SMPP usa una libreria open source, scrive i rapporti nella stessa tabella di stato usata dal webhook ed espone la stessa interfaccia di invio interna del percorso REST.
• Test: gli estratti conto in arabo vengono confermati come UCS-2 con concatenazione corretta su diversi telefoni.
• Rilascio: un paese passa per primo. Dopo il confronto di consegna e tempi dei rapporti con la base REST, seguono gli altri paesi, con REST mantenuto come riserva.

Errori comuni

• Scegliere SMPP per prestigio. Se REST regge il vostro volume, SMPP aggiunge solo lavoro.
• Usare una finestra di 1, poi dare al provider la colpa del basso throughput.
• Non confermare deliver_sm, provocando rapporti reinviati e throttling.
• Riconnettersi in un ciclo serrato dopo una disconnessione, cosa che può sembrare un attacco.
• Mescolare short_message e message_payload nella stessa PDU, causando errori di lunghezza.
• SMPP in chiaro su Internet, che espone credenziali e contenuti.
• Due modelli di stato in una configurazione ibrida, così i report non coincidono.
• Limiti: questa guida descrive la prassi comune. Dimensioni delle finestre, velocità, porte TLS e dettagli dei rapporti variano per provider e account; confermateli durante il provisioning.

Come vi aiuta OmniChannels.ai

OmniChannels.ai offre entrambe le opzioni. La API REST su https://api.broadnet.me usa un Bearer token e copre gli SMS insieme a WhatsApp, RCS, Messenger, Instagram, Telegram, email e notifiche push, con gli stati di consegna inviati al vostro webhook in un unico formato. Per gli SMS ad alto volume, i bind SMPP 3.4 su TLS vengono attivati per account, con IP di origine in allow list, e usano le stesse rotte SMS sulla connettività diretta con gli operatori di BroadNet. Rivenditori e partner wholesale possono avere bind dedicati. Partite dalla documentazione SMPP o dal quickstart, oppure consultate la panoramica per sviluppatori.