Documento: SMS WEB infosmsweb.pdf Data ult. rev.: 23/04/2010 Versione: 1.0 Destinatari: programmatori / sistemisti Pag. 1 di 12
Indice FUNZIONAMENTO... 3 SPEDIZIONI BATCH... 665 I MESSAGGI MULTI... 8 NOTIFICA RICEZIONE MESSAGGI... 9 CODICI DI ERRORE :... 11 ESEMPI :... 12 Pag. 2 di 12
FUNZIONAMENTO Per accedere al gateway SMS di SMS Pubblicità via HTTP e' necessario effettuare una POST all'url: http:// www.topdatmobileservice.it/smsgw/sendsmart.asp? passando i parametri specificati nella sezione INPUT, di questo documento. L'autenticazione può essere effettuata in due modi: in base all'indirizzo IP del client e ad una password (dispositiva) trasmessa in chiaro in base ad un secret-value condiviso (MAC basato su hash MD5) INPUT I possibili parametri da passare al gateway sono: ticket Data Id Operation Rcpt Password From Udh Qty Act rcptbatch idbatch urlbatch TICKET è un parametro obbligatorio se l'autenticazione associata all' account è di tipo MD5. Usato come token di autenticazione. Il valore del ticket deve essere ricavato applicando la funzione hash MD5 (con output in esadecimale, lowercase) alla stringa risultante dalla concatenazione dei parametri: id, operation, rcpt, from, data, password. Il valore del parametro password viene fornito all'atto dell'attivazione dell'account. L'autenticazione è soddisfatta se l'hash MD5 ricalcolato dal gateway sui parametri ricevuti e la copia locale della password, è uguale al ticket ricevuto. Qualora un parametro non venga inserito nella richiesta POST/GET bisogna ometterlo anche dal calcolo del ticket. ID è un parametro obbligatorio. Il suo valore deve essere la login dell'account utilizzato. PASSWORD è un parametro obbligatorio se l'autenticazione associata all' account e' di tipo plainpassword. Il suo valore deve essere la password dispositiva dell'account utilizzato. Pag. 3 di 12
OPERATION è un parametro obbligatorio. Tramite questo parametro è possibile indicare il tipo di messaggio che si intende spedire o richiedere determinate informazioni sull'account che si sta utilizzando. TIPO DI MESSAGGIO: TEXT Il messaggio è di tipo testo MULTI Sono più messaggi che vengono interpretati dal cellulare come un unico SMS OLGO Il messaggio è un logo GLGO Il messaggio è un logo gruppo (Nokia SmartMessaging) operatore (Nokia Smart- Messaging) RING Il messaggio è una suoneria 8BIT Il messaggio è ad 8 bit INFORMAZIONI ACCOUNT: RCPT GETCREDIT Ritorna il credito associato all'account Es.: OK 100000 GETBILL Ritorna il costo del singolo messaggio associato all'account Es.: OK 333 GETMESS Ritorna il numero di messaggi ancora disponibili, con la relativa qualità Es.: OK 10 HQS Sono disponibili ancora 10 messaggi di alta qualità GETNOTIFY Ritorna il numero di notifiche ancora disponibili Es.: OK 1000 GETIP Ritorna l'ip associato all'account o un'espressione regolare in presenza di più IP (uno o più IP differenti, una o più reti differenti). GETURL Ritorna l'url utilizzato per l'inoltro delle notifiche GETMSENT Ritorna il numero di messaggi spediti dal giorno di creazione dell'account. GETNSENT Ritorna il numero di notifiche spedite dal giorno di creazione dell'account. è un parametro obbligatorio. Indica il numero del terminale mobile a cui spedire il messaggio, secondo il formato internazionale +JJxxxyyyzzkk (Es.: +393112224455) FROM è un parametro opzionale. Indica il generante del messaggio. Il suo valore sarà mostrato dal terminale mobile come mittente del messaggio. Sono consentiti due formati, alfanumerico o un numero nel formato internazionale +393112224455 oppure 00393112224455. Il primo formato consente di utilizzare stringhe alfanumeriche di lunghezza compresa tra 1 ed 11 caratteri. Nel secondo caso la sua lunghezza non deve essere superiore a 16 caratteri. DATA è un parametro obbligatorio. Indica il corpo del messaggio. La lunghezza del parametro dipende dal tipo di messaggio che si invia. Per i tipi di operation TEXT il messaggio deve essere in ASCII e la sua lunghezza non deve superare i 160 caratteri. Per i tipi di operation OLGO e GLGO deve essere utilizzato l'encoding OTA, la sua lunghezza non deve superare I 260 byte per OLGO e 266 byte per GLGO. In modalità 8BIT deve contenere il payload, codificato in esadecimale. La sua lunghezza sommata alla lunghezza dell'udh (parametro riportato di seguito, User Data Header) non deve superare i 280 byte. Nel caso di un messaggio Wap push il limite della lunghezza testo + URL è di 126 caratteri. Per i tipi di operation MULTI ogni sms non deve superare i 134 caratteri. UDH è un parametro obbligatorio, solo per la modalità 8BIT, deve contenere lo User Data Header, Pag. 4 di 12
codificato in esadecimale, deve essere omesso il primo ottetto, l'udhl (User Data Header Length) il suo valore è calcolato dal gateway sms. QTY è un parametro opzionale. Indica la qualità del messaggio. i valori che questo parametro può assumere sono : ll Qualità bassa. l Qualità media. h Qualità alta. a Qualità automatica. Se il valore di questo parametro è nullo o differente dai valori possibili (indicati sopra), il gateway sms utilizzerà la qualità di default cioè la qualità automatica. ACT Deve contenere un valore intero decimale di lunghezza massima 20 cifre. Questo valore identificherà il messaggio spedito, e sarà inoltrato al client come notifica di avvenuta ricezione. RCPTBATCH Può contenere una lista di numeri a cui spedire lo stesso messaggio. Ogni numero deve essere espresso come descritto per il parametro rcpt Es.: +39329123311,+39123411101,+39318199199 Consultare la sezione SPEDIZIONI BATCH dello stesso documento. IDBATCH Può contenere un identificativo da associare alla spedizione batch che si sta richiedendo. Il valore sarà restituito al cliente al termine della spedizione attraverso una POST HTTP ad URL precedentemente settata. L'identificativo della spedizione batch non può superare lunghezza 255 e può contenere esclusivamente caratteri compresi nell'insieme [AZaz09]. Es.: AF1234U761JJ Consultare la sezione SPEDIZIONI BATCH dello stesso documento. URLBATCH può contenere un URL che sarà richiamato dal Gateway SMS al termine della spedizione batch richiesta. I parametri che saranno passati sono descritti nella sezione SPEDIZIONI BATCH. Pag. 5 di 12
SPEDIZIONI BATCH Attraverso una spedizione batch è possibile, effettuando una singola POST o GET HTTP, inviare uno stesso messaggio di testo a più contatti. Per effettuare una spedizione batch, è necessario inserire la lista dei numeri destinatari del messaggio come valore del parametro rcptbatch. Ogni destinatario deve essere separato dal successivo con un carattere virgola (ignorare le virgolette) :,. Esempio di lista : +39341123111,+39328188111,+44178811112,+34166110909 Limiti: La lista non può contenere più di 5000 destinatari. I destinatari in eccedenza non saranno presi in considerazione all'atto della spedizione. Per far si che la spedizione batch venga presa in carico dal gateway SMS la lista deve contenere minimo 2 destinatari. In risposta alla POST HTTP effettuata, il gateway SMS ritornerà la stringa OK BATCH, nel caso in cui la richiesta di spedizione venga presa in carico, altrimenti, KO BATCH nel caso in cui la richiesta non venga presa in carico. Esiste la possibilità di ricevere una notifica di avvenuta spedizione del batch. Attraverso una POST HTTP lato gateway SMS, verso un URL precedentemente settato come valore del parametro urlbatch. Il valore di questo parametro non può superare lunghezza 255. Consultare la voce Notifica avvenuta spedizione presente di seguito. Esempio di urlbatch : http://www.example.com/cgibin/smsbatch.cgi Parametri da accettare : account conterrà la login dell'account per il quale è stata effettuata la spedizione. ticket conterrà il valore di idbatch precedentemente settato all'atto della richiesta di spedizione reportpath indica il path completo del report da scaricare via FTP come descritto di seguito reportname indica il solo nome del report da scaricare via FTP come descritto di seguito success conterrà il numero di messaggi inviati con successo error conterrà il numero di messaggi per il quale si è riscontrato un errore. status conterrà un testo in lingua italiana che riepiloga lo stato finale della spedizione. E' possibile identificare la spedizione batch che si sta andando ad effettuare utilizzando il parametro idbatch. Questo valore sarà il valore contenuto nel parametro ticket nel momento in cui il gateway SMS andrà ad effettuare la POST HTTP di notifica avvenuta spedizione. Esempio di una spedizione batch (i parametri sono stati elencati per chiarezza) : http://topdatmobileservice.it//smsgw/sendsmart? id=login &password=p4ssw0rd &from=test &operation=text &data=batch%20http &rcptbatch=%2b39341241771,%2b3912331001,2b448819911 &idbatch=aaa111bbb222 &urlbatch=http://www.example.com/cgibin/recvbatchnotify.cgi Il gateway SMS ritornerà come risposta la stringa OK BATCH, effettuerà la spedizione ed al termine, attraverso una POST http all'url settato in urlbatch, notificherà l'avvenuta spedizione del batch con identificativo AAA111BBB222, come settato in idbatch. Pag. 6 di 12
Lato client, dopo aver ricevuto la POST sarà possibile collegarsi via FTP all'indirizzo : smsftp.titisms.it alla porta 21 ed effettuare una get del path contenuto nel parametro reportpath (consultare il documento smsbatch.pdf per maggiori informazioni) esempio : supponiamo di aver ricevuto questi due valori attraverso la POST di notifica avvenuta spedizione : reportpath = /path/reportspedizione.txt reportname = reportspedizione.txt... ftp> ftp> get /path/reportspedizione.txt reportspedizione.txt ftp> quit... si avrà in locale un file ASCII di nome reportspedizione.txt che conterrà il report della spedizione batch. Consultare il documento smsbatch.pdf alla sezione I REPORTS Limiti : E' possibile effettuare solo spedizioni batch di messaggi testuali. (operation TEXT). Note : Per far si che una spedizione batch venga presa in carico dal gateway SMS è necessario che la lista di numeri sia di almeno due contatti. Questa tipologia di spedizione è un wrapper delle spedizioni batch che è possibile effettuare attraverso il protocollo FTP, per maggiori informazioni riguardo le spedizioni FTP consultare il documento smsbatch.pdf Pag. 7 di 12
I MESSAGGI MULTI I messaggi MULTI sono quella tipologia di SMS che quando ricevuti da un cellulare vengono accorpati in un unico SMS permettendo così all'utente di inviare un testo più lungo dei 160 caratteri consentiti dallo standard GSM. I messaggi MULTI sono supportati solamente con sms di Alta qualità. Per utilizzare questa tipologia di messaggi bisogna settare: il parametro operation = MULTI il parametro udh = aabbcc dove aa : id del messaggio dove bb : numero totale delle parti del messaggio dove cc : parte che si sta inviando Di seguito alcuni esempi di realizzazione di un messaggio multi. Messaggio suddiviso in due parti prima parte : operation=multi&udh=010201&data=primaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...AAA seconda parte : operation=multi&udh=010202&data=secondaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...AAA Messaggio suddiviso in tre parti prima parte : operation=multi&udh=0d0301&data=primaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAAAAAAAAAAAAAAAAA...AAA seconda parte : operation=multi&udh=0d0302&data=secondaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAAAAAAAAAAAAAAAAA...AAA terza parte : operation=multi&udh=0d0303&data=terzaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAAAAAAAAAAAAAAAAA...AAA Non è da sottovalutare l'importanza dell'id del messaggio (primo ottetto) in quanto se si vanno ad inviare due messaggi multipli contemporaneamente allo stesso numero di telefono con lo stesso ID il messaggio potrebbe essere visualizzato male o non visualizzato per niente. Utilizzando la modalità MULTI ogni sms non dovrà superare i 134 caratteri, questo perchè i 26 caratteri rimanenti dei 160 di un SMS standard vengono utilizzati come identificativi e per altri parametri interni dei messaggi MULTI. Pag. 8 di 12
NOTIFICA RICEZIONE MESSAGGI La notifica ricevuta, in questo caso, è la mobile delivery notification, i dati ricevuti saranno composti da: data e ora in cui il messaggio è stato recapitato al terminale mobile e lo stato del messaggio. Stato del messaggio: Lo stato del messaggio, consiste nella possibilità di ricevere oltre alla notifica di avvenuta ricezione anche la notifica di NON avvenuta ricezione con la causa della mancata consegna del messaggio verso il terminale mobile da parte dell' SMSC. Lo stato in caso di consegna sarà uguale a : Delivered (Consegnato). Lo stato, in caso di mancata consegna del messaggio, potrà essere uguale ad uno dei seguenti messaggi : Unknown subscriber (Numero inesistente) VP exceed (Destinatario Irraggiungibile) per oltre 48 ore Teleservice not provisio. (Numero non abilitato in ricezione) Operator Barring (Numero bloccato dall'operatore) MT number is unknown in the MT network's HLR (Numero sconosciuto nell'home Location Register) (I messaggi di mancata consegna variano in base all'operatore utilizzato) Di seguito sono riportati i parametri che il CGI lato client dovrà accettare in ingresso. Parametri: I parametri sono : Act Date Time Status Act conterrà un valore intero decimale di lunghezza massima 20 cifre. Sarà lo stesso valore precedentemente inviato dal client al gateway SMS per identificare il messaggio spedito. date conterrà la data di ricezione del messaggio nel seguente formato ggmmaaaa (Es.: 23012003) Nel caso di mancata consegna del messaggio, il campo data sarà uguale a : 000000 time conterrà l'ora di ricezione del messaggio nel seguente formato hh:mm:ss (Es.: 09:24:55) Nel caso di mancata consegna del messaggio, il campo time sarà uguale a : 99:99:99 status conterrà lo stato del messaggio. Il dato contenuto sarà di tipo testo di lunghezza mai superiore ai 256 caratteri. Pag. 9 di 12
OUTPUT: La transazione HTTP ritorna un contenuto di tipo "text/html". Se l'inoltro è andato a buon fine ritornerà la stringa "OK" seguita dal credito sottratto a quella spedizione. In presenza di errori ritornerà la stringa "KO", eventualmente seguita da un testo esplicativo. In presenza di spedizioni batch il gateway SMS ritornerà una stringa OK BATCH in caso di esito positivo, oppure KO BATCH in caso di esito negativo. Esito positivo sta a significare solo ed esclusivamente che la richiesta di spedizione batch è stata presa in carico dal gateway SMS. Esito negativo, la richiesta non è stata presa in carico. Esempio : OK 378 OK indica che la transazione è andata a buon fine, 378 indica il numero di crediti sottratti all'account dopo aver effettuato quella singola spedizione. Pag. 10 di 12
CODICI DI ERRORE : KO 101 not allowed KO 102 operation not permitted KO 103 bad recipient KO 104 not allowed KO 105 not allowed KO 106 not allowed KO 107 no auth suitable KO 109 carrier problem KO 110 Msg Blocked KO 111 banned KO 124 text too long KO 211 quota_abs reached (credito non disponibile) KO 213 quota_ny reached (notifiche non disponibili) KO 300 System (Internal Error) KO 301 (Connection Problem) KO 302 (Generic Error) KO 303 (Connection Problem) KO 310 type unsupported KO 311 send error KO 400 (Internal Error) KO 401 (Internal Error) KO 402 (Internal Error) KO 500 ERROR (Internal Error) KO 501 ERROR (Internal Error) KO 502 (Internal Error) VINCOLI : L'invocazione della transazione HTTP deve essere effettuata da uno script realizzato dall'utente. In nessun caso l'utente finale deve poter venire a conoscenza delle informazioni di autenticazione passate al gateway SMS. E' pertanto da escludere l'utilizzo da parte degli utenti finali di form HTML che interagiscano direttamente con il gateway SMS. Per contro dovrà essere implementata una funzionalità di "rilancio" server side. Pag. 11 di 12
ESEMPI : Sono riportati di seguito alcuni esempi di GET: Voglio fare una richiesta per verificare il numero di messaggi residui. Per fare questo devo settare il parametro operation=getmess. Ho 2 possibilità per potermi autenticare sul server:.in base all'indirizzo IP del client e ad una password trasmessa in chiaro.in base ad un secretvalue condiviso (MAC basato su hash MD5) Se l'indirizzo IP è stato comunicato ed è stato abilitato avrò: *http://smsweb.titisms.it/smsgw/sendsmart?id=c00000_001&password=123456&operation=getmess Se invece non voglio avere il vincolo dell'indirizzo IP o non voglio trasmettere in chiaro la password devo impostare il parametro ticket calcolando l'md5 della stringa risultante dalla concatenazione dei parametri: id, operation, rcpt, from, data, password. Nel caso i parametri non siano settati non bisogna considerarli nel calcolo del ticket. In questo caso ticket = MD5 C00000_001GETMESS123456 = a512c75a4e89edeab1b450aaea126f25 perciò la richiesta dovrà essere fatta come segue:.../smsgw/sendsmart?id=c00000_001&operation=getmess&ticket=a512c75a4e89edeab1b450aaea126f25 Allo stesso modo è possibile: controllare il credito:.../smsgw/sendsmart?id=c00000_001&password=123456&operation=getcredit controllare le notifiche residue:.../smsgw/sendsmart?id=c00000_001&password=123456&operation=getnotify inviare messaggi: (password in chiaro e IP settato).../smsgw/sendsmart?id=c00000_001&password=123456&operation=text&rcpt=%2b39340123 456 7&from=MITTENTE&data=TESTO&qty=h (ticket MD5).../smsgw/sendsmart?id=C00000_001&operation=TEXT&rcpt=%2b393401234567&from=MITTENTE& data=testo&qty=h&ticket=7ae9e629978d28deb774a3e658779207 dove ticket = MD5 C00000_001TEXT+393401234567MITTENTETESTO123456 = 7ae9e629978d28deb774a3e658779207 Pag. 12 di 12