Gateway SMS HTTP
Il gateway permette di inviare SMS (anche concatenati) personalizzando il mittente.
Tutte le lettere accentate italiane sono supportate nel testo; il mittente ha limiti specifici.
Il gateway permette anche di inviare SMS temporizzati “tra X minuti”.
SMS Gratis (ambiente di sviluppo)
Per gli sviluppatori sono disponibili SMS gratuiti per la fase di sviluppo.
In questa fase è possibile simulare gli invii (non vengono inviati SMS reali e non viene scalato il credito), usando gli SMS veri solo per i test finali.
Gruppi di SMS
SubitoSMS permette di raggruppare tanti SMS in un’unica spedizione quando il testo è identico e deve essere inviato a molti numeri diversi.
Lo stesso numero destinatario non può essere presente due volte nella stessa spedizione.
Flusso normale
1) La tua applicazione effettua una o più chiamate HTTPS verso https://www.subitosms.it/gateway.php passando i parametri.
2) Il gateway risponde con un codice numerico “id” che rappresenta la spedizione.
3) La tua applicazione può: (a) attendere la callback verso una URL preconfigurata; (b) interrogare il gateway passando l’id per leggere lo stato della spedizione.
4) Raggiunto uno stato terminale (-100, -50, 1, 16) non serve consultare oltre il gateway o attendere altre callback.
Se entro 24 ore non viene raggiunto lo stato terminale, considera terminale l’ultimo stato raggiunto.
Esempio: invii un SMS, il telefono è spento → stato 8 (spedito). Se il telefono si accende entro 24 ore e riceve l’SMS → stato 1 (ricevuto). Se resta spento, lo stato può diventare 16 oppure restare a 8. Alcuni utenti/operatori non supportano o disabilitano le delivery report (es. in alcuni contesti USA).
Invio SMS: parametri (GET o POST)
Per inviare uno o più SMS è necessario specificare:
• username: la username ottenuta in registrazione
• password: la password ottenuta in registrazione
• mitt: mittente alfanumerico (o numero di telefono, vedi sotto)
• dest: destinatario (uno o più numeri, vedi sotto)
• testo: testo dell’SMS
• test: se presente, l’SMS non verrà inviato (es. test=1)
• (opz) delay: numero di minuti per ritardare l’invio
Risposta invio
Il gateway risponde con: id:12345678 (cioè “id:” seguito dal codice spedizione).
Se il gateway non ritorna “id:” considera la risposta un errore.
L’unico errore codificato è “credito insufficiente”. Negli altri casi si ottiene un ID e uno stato di invio.
Dettagli sul numero destinatario (dest)
Il numero non deve contenere caratteri o spazi; sono ammessi solo “+” e cifre 0–9.
Per più numeri con lo stesso testo, indica più numeri separati da virgola.
Dettagli sul mittente (mitt)
Se il mittente è alfanumerico (non è un numero di telefono) ha il limite di 11 caratteri e i telefoni non possono rispondere a quei messaggi.
Se usi un numero di telefono come mittente, il limite degli 11 caratteri non si applica e i telefoni possono rispondere.
In Italia è in vigore una normativa AGCOM sui mittenti: va rispettata per chi invia SMS in Italia, anche tramite operatori esteri.
Dettagli sul testo e SMS lunghi
Gli SMS “tradizionali” arrivano fino a 160 caratteri (7 bit). Per concatenare (SMS lunghi) si usano bit aggiuntivi, quindi la capienza effettiva varia.
In concreto: • 160 caratteri ≈ 1 SMS • 320 caratteri ≈ 3 SMS
Curiosità: alcuni caratteri “costano” più di altri (es. È vs É possono ricadere in tabelle diverse), influenzando il numero di caratteri disponibili per SMS.
Verifica del credito: parametri
Per verificare il credito residuo invia:
• username
• password
• (opz) estero=1 per mostrare anche il credito estero
Risposta credito
Il gateway risponde con: credito:2630 (cioè “credito:” seguito dal valore residuo).
Controllo stato di una spedizione: parametri
Per controllare lo stato invia:
• username
• password
• id (codice ottenuto durante l’invio)
Risposta stato
Per ogni SMS in una spedizione, il gateway ritorna una riga, ad esempio:
dest:+3912345678;stato:1;desc:Ricevuto dal destinatario;
Stato spedizione via HTTP Callback
Nelle preferenze del sito SubitoSMS puoi indicare una URL di callback che il gateway chiamerà a ogni modifica dello stato di consegna.
Il gateway effettua una chiamata POST verso la URL, aggiungendo queste variabili:
• id: codice della spedizione di questo SMS
• dest: numero destinatario in formato internazionale
• stato: stato numerico dell’SMS
Nota: timeout callback 120 secondi. Evita logiche troppo complesse nella pagina di callback.