1. Il Servizio. 2. Protocollo SMS-Server

Транскрипт

1 1. Il Servizio 2. Protocollo SMS-Server 3. Protocollo HTTP Post e Get 3.1) Invio di SMS di testo 3.2) Invio di SMS con testo in formato UNICODE UCS-2 3.3) Simulazione di un invio 3.4) Possibili risposte dalla pagina ASP 4. Protocollo SMPP 5. Servizio Web.ASMX 6. Utilizzo delle DLL 7. Caratteri Supportati 8. Servizi Aggiuntivi 8.1) Monitoraggio 8.2) Controllo Credito 9. Ricezione delivery report Page 1/19

2 1. Il Servizio Questo servizio permette ai clienti di inviare SMS via web. Per poterlo utilizzare è necessario un collegamento ad Internet. La soluzione per spedire i messaggi può essere tarata sulle specifiche esigenze del cliente. Si offrono infatti le seguenti possibilità per spedire i propri messaggi: Protocollo proprietario SMS-Server su Tcp/IP Protocollo HTTP Post o Get Protocollo SMPP Servizio web ASMX DLL Win32 o DLL.NET I metodi sono complementari. E infatti possibile, con un solo account, usufruire di tutti i metodi. L esempio più indicativo è quello di un azienda che utilizza il protocollo SMS-Server per spedire grandi quantità di SMS (ad esempio per la comunicazione con i clienti), e che vuole aggiungere alla propria home page la possibilità di inviare SMS (utilizzando il metodo POST). Il protocollo SMS-Server è consigliato per gli utenti che hanno conoscenze di sviluppo software e vogliono integrare il servizio SMS nelle proprie applicazioni. L'invio tramite protocollo HTTP Post, HTTP Get sono generalmente utilizzati per invii da siti web. In questo caso non è necessario installare alcun software, poiché il trasferimento dei messaggi avviene utilizzando lo standard HTTP. E una soluzione adeguata per il cliente che ha necessità di spedire discrete quantità di messaggi in modo semplice e veloce. Le DLL e il servizio web ASMX possono essere facilmente integrate ed utilizzate negli ambienti di sviluppo più comuni dando la possibilità di aggiungere con poche righe di codice la funzionalità di invio SMS ai propri software. Page 2/19

3 2. PROTOCOLLO SMS SERVER Il protocollo SMS-Server è un protocollo proprietario basato sullo standard Tcp-IP. Per inviare uno o più sms basta aprire un unica connessione, spedire tutto il pacchetto di messaggi ed eventualmente disconnettersi dal server se non si desiderano spedire altri pacchetti di SMS. Non bisogna quindi aprire una connessione per ogni messaggio da inviare. Per ogni connessione basta un record login. Con questo metodo si possono inviare messaggi in Streaming. E possibile inviare al massimo 120 SMS alla volta con un unica operazione di invio La connessione può essere mantenuta aperta semplicemente inviando ogni 2-3 minuti il segnale di Keep Alive, cioè la stringa di login. Connessione via TCP/IP HOST: smsserver.agiletelecom.com PORT: 26 Protocollo SMSServer Ogni pacchetto DATA da inviare dovrà essere trasmesso nel seguente modo: DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h Dove 0Bh = 1 byte che indica inizio pacchetto 03h = 1 byte che indica fine pacchetto CHECKSUM = valore ascii (in decimale) delle due cifre meno significative del checksum esadecimale (2 byte) DATA = pacchetto di dati da inviare Page 3/19

4 PRIMA FASE: LOGIN APPENA STABILITA LA CONNESSIONE VIA SOCKET CON IL SERVER DI AGILE INVIARE IL PROPRIO LOGIN: DATA=06h USER 04h PASSWORD 04h DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h 06h = 1 byte indica RECORD LOGIN 04h = 1 byte SEPARATORE DI CAMPI SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro millesimi = 1 Euro) SECONDA FASE: INVIO DI MESSAGGI (DA RIPETERE PER OGNI PACCHETTO DI SMS DA INVIARE) Per spedire 1 o più SMS via TCP/IP: DATA=05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + ParametroRiservato + 04h + ParametroRiservato + 04h + DELIVERYCODE + 04h (+ 09h + DELAYEDDELIVERY** + 09h) **Il valore DELAYEDDELIVERY ed I separatori 09h sono opzionali nel caso non si voglia utilizzare questa funzinalità) dove NUMBER destinatario in formato internazionale (es ) SENDER nome o numero del mittente (es. Rossi ) TEXT testo del messaggio (Max. 160 caratteri, es. Buongiorno a tutti ) FLASH N (messaggio non in formato flash) o F (messaggio in formato flash) FILENAME nome del pacchetto spedito con relativa estensione (specifica il tipo di SMSTEXT esempio.sms,.uni o.flh).sms per un messaggio testuale standard (default).flh per un sms testuale flash.uni per un sms con testo in Unicode GATEWAY 1 byte numerico. Specifica la qualità del messaggio H=qualità alta (default) M=qualità media DELIVERYCODE codice univoco che l utente deve specificare per la ricezione del delivery report (se non specificato non viene richiesto il delivery report) (Alfanumerico, MAX 20 caratteri, es ) è consigliato generare il codice in base al giorno/ora corrente DELAYEDDELIVERY Campo facoltativo utilizzato per specificare l'ora alla quale inviare I messaggi programmati. Il formato della variabile sarà il seguente: DDT + YYYYMMDDHHNNSS dove: DDT è una stringa costante, YYYY=anno, MM=mese, DD=giorno, HH=ore, NN=minuti, SS=secondi tutti I valori fanno riferimento alla data/ora in formato 24h e GMT+1 (orario Italiano). È obbligatorio specificare la cifra 0 nel caso uno dei valori abbia una cifra sola. es.: invio alle ore 15:03:01 del giorno 22/03/ > DDT DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro = 1 Euro) 1-a) PER SPEDIRE SMS MULTIPLI CON TESTO E/O MITTENTE DIVERSO (senza richiesta di delivery report): DATA=05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + 04h DATA=DATA + 05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + 04h DATA=DATA + 05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + 04h DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro = 1 Euro) Page 4/19

5 1-b) PER SPEDIRE SMS MULTIPLI CON TESTO E/O MITTENTE DIVERSO (con richiesta di delivery report): DATA=05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + DELIVERYCODE + 04h DATA=DATA + 05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + DELIVERYCODE + 04h DATA=DATA + 05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + DELIVERYCODE + 04h DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro = 1 Euro) 2-a) PER SPEDIRE SMS MULTIPLI CON LO STESSO TESTO E MITTENTE (senza richiesta di delivery report): DATA=05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + 04h DATA=DATA + 07h + NUMBER DATA=DATA + 07h + NUMBER DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro = 1 Euro) 2-b) PER SPEDIRE SMS MULTIPLI CON LO STESSO TESTO E MITTENTE (con richiesta di delivery report): DATA=05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY + 04h + 04h + 04h + DELIVERYCODE + 04h DATA=DATA + 07h + NUMBER + 08h + DELIVERYCODE DATA=DATA + 07h + NUMBER + 08h + DELIVERYCODE (ogni delivery code va posto dopo il numero di telefono separandoli con il carattere ascii numero 8 chr(8) ) DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h SI RICEVERA LA RISPOSTA: +OK xxxxx (dove xxxxxx è il credito residuo dell account, espresso in millesimi di Euro = 1 Euro) N.B.: PER OGNI DATO INVIATO TRAMITE TCP/IP AGGIUNGERE DA SPEDIRE= 0Bh + DATA + CHECKSUM + 03h CHECKSUM= VALORE ASCII (IN DECIMALE) DELLE DUE CIFRE MENO SIGNIFICATIVE DEL CHECKSUM ESADECIMALE (2 byte) EXAMPLE: 06h 31h 43h 57h 63h 31h 31h 31h 31h = 1F8h (somma esadecimale) F in ascii = 70 8 in ascii = 56 CHECKSUM= Esempio di s/w in VB che gestisce il protocollo FUNZIONE CHE SERVE PER INCAPSULARE I DATI Private Function SUPPORTO(ByVal dati As String) As String Dim i As Long Dim SUM As Long CALCOLO CHECKSUM i = 1 SUM = 0 Do While i <= Len(dati) SUM = SUM + Asc(Mid(dati, i, 1)) i = i + 1 Loop SUPPORTO = Chr(11) & dati & Right(Hex(SUM), 2) & Chr(3) End Function Page 5/19

6 FUNZIONE PER IL LOGIN AL SERVER Private Function LOGGAMI(ByVal USER As String, ByVal PSWD As String) As String LOGGAMI = Chr(6) & USER & Chr(4) & PSWD & Chr(4) End Function FUNZIONE CHE CREA UN NUOVO SMS Private Function CREASMS(MOBILENUMBER As String, ByVal MITTENTE As String, ByVal TESTO As String, ByVal FLASH As String, ByVal NOMEFILE As String, ByVal GATEWAY As Integer) As String CREASMS = Chr(5) & MOBILENUMBER & Chr(4) & MITTENTE & Chr(4) & TESTO & Chr(4) & FLASH & Chr(4) & NOMEFILE & Chr(4) & GATEWAY & Chr(4) End Function Private Sub SPEDISCISMS Dim DaSpedire as String DaSpedire = SUPPORTO(CREASMS( , MioMitt, Prova test, N, prova.sms, H )) Ora la stringa DaSpedire deve essere inviata tramite una connessione TCP/IP di un socket End Sub Esempio di listato PHP che gestisce il protocollo <?php $debug = 1; set_time_limit(0); $GATEWAY = H; # Possibili valori: H (default) per qualità alta o M per qualità media $host = "smsserver.agiletelecom.com"; $port = 26; $userid = "test"; //username $passwd = "test"; //password function SendSMS($text,$dest,$sender) global $conn; $str = wrap(msg($text,$dest,$sender,"myfile.sms")); fputs($conn,$str); $str = fgets($conn,128); return $str." - ".$errno." - ".$errstr; function SendSMSDelayed($text,$dest,$sender,$deliverycode,$delaydelivery) global $conn; $str = wrap(msgdelayed($text,$dest,$sender,"myfile.sms",$deliverycode,$delaydelivery)); fputs($conn,$str); $str = fgets($conn,128); return $str." - ".$errno." - ".$errstr; function xconnect() global $host,$port,$conn; $conn = fsockopen ($host, $port, $errno, $errstr, 10); if (!$conn) echo "Error happend on ($host:$port): $errstr ($errno)<br>\n"; return 0; $str = wrap(pwd()); if($debug) print "$str<br>\n"; fputs($conn,$str); if($debug) print "<br>after pwd: ".fgets($conn,128)."<br>\n"; return $conn; function xdisconnect() global $conn; fclose($conn); function wrap($data) Page 6/19

7 $chk = 0; $len = strlen($data); for($i=0;$i<$len;$i++) $chk+=ord(substr($data,$i,1)); $chk = sprintf("%02x",$chk%256); return "\x0b$data$chk\x03"; # $POSSIBILI VALORI: # file.sms # file.uni # file.flh function msg($text,$dest,$sender,$type) global $GATEWAY; return "\x05$dest\x04$sender\x04$text\x04n\x04$type\x04$gateway\x04"; function msgdelayed($text,$dest,$sender,$type,$deliverycode,$delaydelivery) global $GATEWAY; return "\x05$dest\x04$sender\x04$text\x04n\x04$type\x04$gateway\x04\x04\x04$deliverycode\x04\x09$delaydelivery\x09"; function pwd() global $userid,$passwd; return "\x06$userid\x04$passwd\x04";?> <?php //insert the following instruction in the web page where you have to perform the sms sending //array of phone numbers $numbersms=array(" "," "," "," "); //sms text $txt_sms="text of the message"; //sender name $sender="mittente"; //delivery code (only for SendSMSDelayed function) $deliverycode=date("ymdhns").rand(0,99999); //it allows to send delayed sms (only for SendSMSDelayed function) - it's necessary to write always day and month with 2 digits. Example: hour 15:03:01 day 22/03/ > DDT $delaydelivery="ddtyyyymmddhhmmss"; //Example: to be delivered in date 2012/12/31 at 23:59:40 you have to set it to: DDT //Send sms if(xconnect()) //if connected //Send an sms to all numbers of array "numbersms" while(list ($key, $val) = each($numbersms)) $msg = SendSMS($txt_sms,$val,$sender); if (strstr($msg,'+ok')) echo "Sms sent<br>"; else echo "Sms not sended. $msg<br>"; xdisconnect(); else echo "Failed: Could not connect - $errno - $errstr "; //Send delayed sms /*if(xconnect()) //if connected //Send a delayed sms to all numbers of array "numbersms" while(list ($key, $val) = each($numbersms)) $msg = SendSMSDelayed($txt_sms,$val,$sender,$deliverycode,$delaydelivery); Page 7/19

8 xdisconnect(); if (strstr($msg,'+ok')) echo "Sms sent<br>"; else echo "Sms not sended. $msg<br>"; else echo "Failed: Could not connect - $errno - $errstr "; */?> Page 8/19

9 3. PROTOCOLLO HTTP POST E GET Per inviare SMS via post basta spedire una richiesta HTTP POST al seguente indirizzo o una richiesta HTTP GET al seguente indirizzo Per entrambi I metodi è necessario specificare I valori delle seguenti variabili: smstext smsnumber smssender smsgateway smstype smsuser smspassword smsdelivery smsdelayed max 640 char, testo del messaggio (160 caratteri se è un sms singolo; 153 caratteri per ogni sms in caso di long message) max 16 caratteri, numero telefonico dell utenza di destinazione in formato internazionale, E possibile mettere fino a 100 numeri di destinazione in formato internazionale separato da ; max 16 cifre per il numero telefonico del mittente in formato internazionale oppure max 11 caratteri per una stringa di testo alfanumerico Indica il tipo di qualità da utilizzare per l'invio del messaggio (H = qualità alta, M = qualità media) (Campo opzionale, se non specificato sarà usata la qualità alta) tipo del messaggio file.sms per spedire SMS standard di testo file.flh per spedire SMS FLASH di testo file.uni per spedire SMS di testo in formato UNICODE l user del vostro account la password del vostro account campo facoltativo usato per identificare univocamente il messaggio nel caso in cui si voglia richiedere la notifica di ricezione del messaggio Campo facoltativo utilizzato per specificare l'ora alla quale inviare I messaggi programmati. Il formato della variabile sarà il seguente: YYYYMMDDHHNNSS dove: YYYY=anno, MM=mese, DD=giorno, HH=ore, NN=minuti, SS=secondi tutti I valori fanno riferimento alla data/ora in formato 24h e GMT+1 (orario Italiano). È obbligatorio specificare la cifra 0 nel caso uno dei valori abbia una cifra sola. es.: invio alle ore 15:03:01 del giorno 22/03/ > La pagina smshurricane.asp darà conferma dell avvenuto trasferimento del messaggio. 3.1 Invio di SMS di testo I parametri essenziali per l'invio di sms di tipo testo sono: smsuser, smspassword, smsnumber, smstext. Ecco un esempio di richiesta POST: POST /smshurricane3.0.asp HTTP/1.1 Host: post.agiletelecom.com Content-Length: 129 Connection: Keep-Alive Content-type: application/x-www-form-urlencoded Accept-Language: it Cache-Control: no-cache smsuser=user&smspassword=password&smsnumber=%2b &smssender=test&smstext=ciao%20come %20va&smsGATEWAY=H&smsTYPE=file.sms&smsDELIVERY= _A1 Page 9/19

10 Risposta da SMSHurricane3.0.asp ****************************************** HTTP/ Continue Server: SMSDriver POST/1.0 Date: mar, 08 apr :28:41 GMT HTTP/ OK Server: SMSDriver POST/1.0 Date: mar, 08 apr :28:41 GMT Content-Length: 136 Content-Type: text/html Set-Cookie: ASPSESSIONIDACCSTDCT=MDKLNEGAJIIHAMFJIDBLNBIM; path=/ Cache-control: private <html> <head> <title>smsgateway</title> </head> <body bgcolor="#ffffff"> +Ok </body> </html> Ecco un esempio di richiesta GET: GET /smshurricaneget3.0.asp?smsuser=user&smspassword=password&smsnumber=%2b &smssender=test&smstext=ciao %20come%20va&smsGATEWAY=H&smsTYPE=file.sms&smsDELIVERY= _A1 HTTP/1.1 Host: post.agiletelecom.com Content-Length: 0 Connection: Keep-Alive Content-type: application/x-www-form-urlencoded Accept-Language: it Cache-Control: no-cache Risposta da SMSHurricaneGET3.0.asp ****************************************** HTTP/ Continue Server: SMSDriver POST/1.0 Date: ven, 18 apr :06:51 GMT HTTP/ OK Server: SMSDriver POST/1.0 Date: ven, 18 apr :06:51 GMT Content-Length: 113 Content-Type: text/html Set-Cookie: ASPSESSIONIDACCSTDCT=MDKLNEGAJIIHAMFJIDBLNBIM; path=/ Cache-control: private <html> <head> <title>smsgateway</title> </head> <body bgcolor="#ffffff"> +Ok </body> </html> Page 10/19

11 3.2 Invio di SMS con testo in formato UNICODE UCS-2 Unicode è uno standard che attribuisce un numero univoco ad ogni carattere, indipendentemente dalla piattaforma, dall'applicativo, dalla lingua. Costituisce l'implementazione ufficiale dello standard internazionale ISO/IEC UCS-2. Utilizzando questo formato con un sistema di messaggistica via SMS si ha la possibilità di spedire, verso i cellulari compatibili, caratteri diversi da quelli presenti nell alfabeto latino standard. E possibile trovare maggiori informazioni sullo standard Unicode al sito mentre le tabelle dei caratteri Unicode si trovano su Per inviare un messaggio utilizzando caratteri Unicode bisogna spedire i seguenti dati: smsnumber smssender smstext smsuser smspassword smsgateway smstype smsdelivery numero del destinatario (max 16 cifre, numero telefonico dell utenza di destinazione in formato internazionale, ) max 16 cifre per il numero telefonico del mittente in formato internazionale oppure max 11 caratteri per una stringa di testo (NON IN FORMATO UNICODE) esadecimale dei caratteri unicode da spedire (senza spazi tra essi) (max 280 caratteri, 70 visualizzati sul cellulare) il proprio user name la propria password Indica il tipo di qualità da utilizzare per l'invio del messaggio (H = qualità alta, M = qualità media) (Campo opzionale, se non specificato sarà usata la qualità alta) file.uni campo facoltativo usato per identificare univocamente il messaggio nel caso in cui si voglia chiedere la notifica di ricezione. Nel testo unicode 4 caratteri corrispondono a 2 byte in formato esadecimale. Esempio: Per spedire utilizzando caratteri Unicode la parola Ciao si dovrà immettere campo smstesto la seguente stringa: F Seguendo la tabella dei caratteri Unicode (Basic Latin), infatti 0043 = C 0069 = I 0061 = a 006F = o 3.3 Simulazione di un invio Inviando un SMS e ponendo come destinatario " " il messaggio non viene spedito ma viene fatta una simulazione d invio. Il programma in pratica controlla la corretta sintassi del messaggio e comunica all'utente il risultato della simulazione. Le simulazioni non vengono contate come messaggi inviati, quindi non sono addebitate all'utente. Dim SIMULAZIONE as Boolean If SIMULAZIONE = False Then DESTINATARIO = Numero Else DESTINATARIO = " " End If Page 11/19

12 3.4 Possibili risposte dalla pagina ASP Risposta dalla pagina ASP Nessuna risposta +Ok xxxxx -Err 001 -Err 002 -Err 004 -Err 005 -Err 006 -Err 007 -Err 008 -Err 009 -Err 011 -Err 012 -Err 013 -Err 090 Significato Timeout/Indirizzo errato/server Down Messaggio accettato, il credito in millesimi di Euro è xxxxx User e/o password incorretti Crediti esauriti Numero destin. non corretto Parametro smsnumber mancante Parametro smstext mancante Messaggio non abilitato Errore del server nell'accettazione del messaggio Client time-out Parametro smsuser mancante Parametro smspassword mancante Parametro smsnumber mancante Troppe sessioni attive 4. Protocollo SMPP Lo standard SMPP è un protocollo sviluppato appositamente per l'invio di SMS tramite connessioni Tcp-Ip. Per utilizzarlo è necessario sviluppare un software che gestisca una connessione di tipo transmitter in modalità sincrona. I parametri per la connessione sono I seguenti: Host Modalità Porta 7000 System Id Password TON 1 NPI 1 DCS 0 smpp.agiletelecom.com Transmitter modalità sincrona User name della vostra registrazione Password della vostra registrazione Per mantenere apera la connessione inviare un Enquire_Link ogni 60 secondi. Il numero del destinatario va specificato senza il + o lo 00 iniziale (es diventa ) Per ulteriori informazioni sul metodo SMPP fate riferimento alla documentazione disponibile al link Page 12/19

13 5. Servizio Web.ASMX L' ASMX permette di integrare al proprio progetto funzioni di invio SMS attraverso un web service. Utilizzando il servizio web all'indirizzo si potranno includere all'interno del proprio software le seguenti funzioni in modo facile e veloce Ask_Credit Send_Message Send_Message_Unicode Send_Message_on_Gate Ask_Credit: permette di richiedere il credito residuo nel proprio account specificando user e password: Ask_Credit (string User, string Password) Nome Parametro Tipo di Dato Descrizione User Stringa Nome utente del proprio account Password Stringa Password del proprio account Send_Message: è utilizzato per inviare l'sms semplicemente specificando i dati dell'utente e del messaggio da inviare: Send_Message (string User, string Password, string Originator, string Destinations, string Message, boolean HighQualitySMS, string DeliveryCode) Nome Parametro Tipo di Dato Descrizione User Stringa Nome utente del proprio account Password Stringa Password del proprio account Originator Stringa Nome o numero che verrà visualizzato come mittente del messaggio Destinations Stringa Numero di cellulare del destinatatio Message Stringa Testo del messaggio HighQualitySMS Boolean Indica la qualità di spedizione dell'sms. Se il parametro è impostato a true si seleziona l'alta qualità, altrimenti la media qualità. DeliveryRequestCode Stringa Codice che identifica univocamente il messaggio necessario solo se si neccessita della notifica di ricezione. (*) (*) Nota: Per poter ricevere la notifica di ricezione è necessario creare una pagina web in grado di accettare un post dal server Agile Telecom. (Vedere capitolo 9). Page 13/19

14 Send_Message_Unicode: è utilizzato per inviare l'sms in formato Unicode specificando i dati dell'utente e del messaggio da inviare: Send_Message_Unicode (string User, string Password, string Originator, string Destinations, string Message, boolean HighQualitySMS, string DeliveryCode) Nome Parametro Tipo di Dato Descrizione User Stringa Nome utente del proprio account Password Stringa Password del proprio account Originator Stringa Nome o numero che verrà visualizzato come mittente del messaggio Destinations Stringa Numero di cellulare del destinatatio Message Stringa Testo del messaggio HighQualitySMS Boolean Indica la qualità di spedizione dell'sms. Se il parametro è impostato a true si seleziona l'alta qualità, altrimenti la media qualità. DeliveryCode Stringa Codice che identifica univocamente il messaggio necessario solo se si neccessita della notifica di ricezione. (*) (*) Nota: Per poter ricevere la notifica di ricezione è necessario creare una pagina web in grado di accettare un post dal server Agile Telecom. (Vedere capitolo 9). Send_Message_on_Gate: Funzione ad uso esclusivo per chi ha esigenze specifiche, utilizzabile solamente previo accordo con il reparto tecnico di Agile Telecom. string Send_Message_on_Gate (string User, string Password, string Originator, string Destinations, string Message, Gateway, string DeliveryCode) Nome Parametro Tipo di Dato Descrizione User Stringa Nome utente del proprio account Password Stringa Password del proprio account Originator Stringa Nome o numero che verrà visualizzato come mittente del messaggio Destinations Stringa Numero di cellulare del destinatatio Message Stringa Testo del messaggio Gateway Stringa Indica il Gateway da usare per inviare il messaggio DeliveryCode Stringa Codice che identifica univocamente il messaggio necessario solo se si neccessita della notifica di ricezione.(*) (*) Nota: Per poter ricevere la notifica di ricezione è necessario creare una pagina web in grado di accettare un post dal server Agile Telecom. (Vedere capitolo 9). Page 14/19

15 Per le funzioni Send_Message, Send_Message_Unicode e Send_Message_on_Gate il server restituisce le seguenti risposte: Risposta dalla pagina ASP Nessuna risposta +Ok xxxxx -Err 001 -Err 002 -Err 004 -Err 005 -Err 006 -Err 007 -Err 008 -Err 009 -Err 011 -Err 012 -Err 013 -Err 090 Significato Timeout/Indirizzo errato/server Down Messaggio accettato, il credito in millesimi di Euro è xxxxx User e/o password incorretti Crediti esauriti Numero destinatario non corretto Parametro smsnumber mancante Parametro smstext mancante Messaggio non abilitato Errore generico a lato server durante l'invio del messagio Time-out del client User non specificato Password non specificata Numero del destinatario non specificato Troppe sessioni attive Esempio in c# Nota: E' necessario aggiungere all'applicazione un Web Reference contenente l'url File Form.cs using AgileEsempio.com.agiletelecom.www; namespace AgileEsempio public partial class Form1 : Form AgileTelecomSMS SMS = new AgileTelecomSMS(); private void Form_Load(object sender, EventArgs e) private void buttongetcredit_click(object sender, EventArgs e) labelcredit.text = SMS.Ask_Credit(textBoxUser.Text, textboxpassword.text); private void buttonsendsms_click(object sender, EventArgs e) labelresponse.text = SMS.Send_Message(textBoxUser.Text, textboxpassword.text, textboxsender.text, textboxdestination.text, textboxbody.text, true, DeliveryCode); Page 15/19

16 6. Utilizzo delle DLL Tramite la nostra DLL è possibile inviare SMS utilizzanto il metodo Http-Post ad un massimo di 100 numeri di destinazione con una sola richiesta e utilizzando un metodo veloce e semplice. Una volta inclusa la DLL nel progetto basterà dichiarare una variabile di tipo SMSDriverLib come nell esempio di VB: Esempio: Dim POST As New SmsDriverLib Una volta dichiarata la variabile si devono impostare i parametri per l invio: user name, password e indirizzo della pagina ASP. Esempio: POST.smsUSER = txtuser.text POST.smsPASSWORD = txtpassword.text POST.URL = In seguito si devono inserire i numeri di destinazione del messaggio. Questo semplice procedimento va ripetuto per ogni destinatario sino ad un massimo di 100 (N.B.: si possono aggiungere anche numeri di test come ) Esempio: POST.Add_Gsm( ) Ogni volta che si richiama questo metodo esso restituisce un valore di tipo Boolean (vero o falso) a seconda che l inserimento sia andato a buon fine o no. Infine si richiama il metodo Send_SMS che invierà la richiesta post alla pagina ASP. Il metodo restituisce un valore di tipo stringa contenente la risposta della pagina ASP o un eventuale errore della DLL (vedi tabella seguente e tabella delle risposte della pagina ASP al paragrafo 3.7). I parametri di questo metodo sono in ordine -Timeout (in secondi) -Mittente del messaggio -Testo del messaggio -Numero del gateway (H = Qualità alta, M = Qualità media) -Tipo di SMS (smstype) -Network code -Delivery code Ecco un esempio sempre in V.B. di come poter richiamare il metodo: POST.Send_Sms(10, Prova, SMS di prova da DLL, 0, "file.sms", "") Risposta dalla pagina ASP Nessuna risposta +Ok xxxxx -Err 101 -Err 102 -Err 103 -Err 104 -Err 105 -Err 106 Significato Timeout/Indirizzo errato/server Down Messaggio accettato, il credito in millesimi d Euro è xxxxx Nessun destinatario Network code non corretto URL non corretto HOST non corretto Pagina non trovata Errore generico con relativa descrizione Page 16/19

17 7. Caratteri Supportati Di seguito trovate la tabella dei caratteri supportati dal nostro sistema SMS. Non tutti i gateway riescono però a supportare tutti i caratteri della seguente tabella. Si consiglia quindi di testare prima i caratteri diversi dalle lettere e dalle cifre col gateway che si intende utilizzare. Per inviare un sms standard contenente caratteri greci nel testo utilizzando i gateway che li supportano, è necessario sostituire il carattere stesso con un carattere speciale che, al momento dell invio verso il cellulare, verrà convertito nel corrispondente carattere greco. Lettera Greca Nome Lettera Greca Carattere da Spedire Valore Ascii Decimale del carattere da spedire Valore Ascii Esadecimale del carattere da spedire Γ Gamma à 195 0xC3 Λ Lambda Ë 203 0xCB Θ Theta È 200 0xC8 Ξ Xi ï 239 0xEF Π Pi Ð 208 0xD0 Σ Sigma Ó 211 0xD3 Φ Phi (Fi) á 225 0xE1 Ψ Psi â 226 0xE2 Ω Omega Ù 217 0xD9 Δ Delta ã 227 0xE3 Page 17/19

18 8. Servizi Aggiuntivi 8.1) Monitoraggio Il servizio di monitoraggio è uno strumento utile per il controllo dello stato attuale del servizio. E' possibile visualizzare direttamente dalla nostra home page lo stato effettivo dei test. Ogni ora circa viene controllato e verificato l'intero ciclo, dalla spedizione alla effettiva ricezione degli SMS. Questo sistema di monitoraggio permette velocemente di avere un'idea generale dello stato del servizio, oltre che fare risparmiare l'intero costo del messaggio testando il funzionamento di esso da parte dell'utente finale. E' possibile anche verificare lo stato del servizio, senza navigare manualmente nel sito, tramite una semplice chiamata HTTP, che ritornerà un HTML facilmente interpretabile. Per controllare automaticamente bisogna richiamare il seguente link: Lo script accetta parametri come QueryString dove: P = prefisso internazionale C = nome del carrier che appare nella HOME PAGE Ecco alcuni esempi di come poter utilizzare questo servizio: Per controllare lo stato del servizio verso tutti gli operatori Italiani Per controllare lo stato del servizio verso Italia TIM 8.2) Controllo Credito Il servizio di controllo credito permette di richiedere in qualsiasi momento ed in modo gratuito il credito residuo del proprio account tramite una semplice richiesta HTTP-GET al seguente indirizzo: I parametri da passare alla pagina asp sono i seguenti: smsuser = Nome utente del proprio account smspassword = Password del proprio account ad esempio Si riceverà una risposta del tipo Risposta dalla pagina ASP Nessuna risposta +Ok xxxxx -Err 001 Significato Timeout/Indirizzo errato/server Down Messaggio accettato, il credito in millesimi di Euro è xxxxx User e/o password incorretti Page 18/19

19 9. Ricezione delivery report Le notifiche di ricezione dei messaggi possono essere ricevute tramite metodo post a condizione di avere una pagina web in grado di accettare un post (dal server Agile Telecom) con i seguenti parametri: ID_SMS DELIVERY_STATUS DELIVERY_DATETIME DESTINATION ID_SMS l'invio è il codice scelto dall'utente che identifica univocamente il messaggio e che deve essere stato specificato durante tramite il parametro smsdelivery. DELIVERY_STATUS è lo stato finale del messaggio che indica se il messaggio è stato ricevuto dal destinatario e potrà avere i seguenti valori: VALORE RICEVUTO SIGNIFICATO DESCRIZIONE 0 UNKNOWN L'SMSC non ha ancora fornito lo status del messaggio. 2 REJECTED L'SMSC ha rifiutato il messaggio. 3 DELIVERED L'SMSC ha consegnato correttamente il messaggio al destinatario finale. 4 EXPIRED L'SMSC non è riuscito a consegnare il messaggio nel tempo disponibile. 6 UNDELIVERABLE L'SMSC non è in grado di consegnare il messaggio. DELIVERY_DATETIME indica la data e ora nel seguente formato YYYYMMDDHHNNSS relativa allo status del messaggio. DESTINATION indica il destinatario del messaggio Ad ogni post inviato dal nostro server il client dovrà rispondere con una stringa contenente +OK in modo che il delivery venga archiviato dal nostro server e non venga notificato ulteriormente. Una volta ricevuti i dati il cliente dovrà memorizzarli in base alle proprie esigenze, ad esempio salvandoli su un database. L'indirizzo URL della pagina va impostato nella sezione dettagli dell'area clienti nel sito Page 19/19