GATEWAY SMS KYRON.IT Documentazione tecnica Versione 1.0 del 21/9/2004

Transcript

1 GATEWAY SMS KYRON.IT Documentazione tecnica Versione 1.0 del 21/9/2004

2 1. INTRODUZIONE Gli utenti autorizzati all utilizzo dei servizi SMS Kyron possono inviare messaggi SMS da applicazioni custom che utilizzino il protocollo TCP/IP e la rete Internet. Questo si ottiene utilizzando il protocollo HTTP per l invio di un pacchetto XML contenente la struttura dati da inviare oppure inviando le variabili con chiamate in POST o GET. Un metodo alternativo per l'invio di SMS consiste nell'utilizzo di un comune client di posta elettronica. In questo caso le funzionalità saranno limitate e i parametri andranno inseriti all'interno di un messaggio di posta. E inoltre disponibile all interno del pannello di controllo del sito Kyron.it un interfaccia web per l invio di messaggi SMS; questa modalità non supporta l invio di suonerie, loghi e messaggi flash CONDIZIONI DI UTILIZZO Le seguenti condizioni devono essere rispettate per poter utilizzare il gateway SMS: Un account utente deve esistere sul sistema Kyron; i dati per l autenticazione di questo account utente dovranno essere inseriti nelle richieste inviate al gateway SMS. Il credito di questo account deve poter permettere l invio del/dei messaggi SMS; eventuali messaggi inviati al gateway con account con fondi insufficienti non verranno consegnati e il gateway ritornerà un messaggio di errore. 2. ACCESSO AL GATEWAY TRAMITE HTTP Per poter trasmettere richieste di invio messaggi alla nostra piattaforma l applicazione del cliente dovrà stabilire una connessione al gateway: gateway server: sms.kyron.it porta: 80 (HTTP) o 443 (HTTP/SSL) protocollo: TCP Il server supporta connessioni SSL con chiavi a 128 bit di lunghezza. In caso di codici di ritorno negativi nessuna applicazione dovrà riprovare a mandare il messaggio che ha dato il risultato negativo; in questo caso il nostro gateway ha ricevuto il messaggio ma non è stato in grado di consegnarlo e qualsiasi ulteriore tentativo verrà rifiutato con il medesimo errore PARAMETRI DI TRASMISSIONE Per ogni richiesta http può essere inviato un messaggio SMS a massimo duecento destinatari diversi. Per inviare messaggi SMS ad una quantità maggiore di destinatari è necessario che venga richiamato il gateway SMS più volte con pacchetti di massimo 200 destinatari per ogni chiamata. Di seguito parametri per la chiamata allo script CGI: AUTENTICAZIONE ELEMENTO USERNAME PASSWORD DESCRIZIONE Obbligatorio - indirizzo abilitato all accesso al pannello di controllo Kyron.it Obbligatorio password del cliente DATI DEL MESSAGGIO ELEMENTO DESCRIZIONE pag 2

3 ORIGINATOR MESSAGETYPE MESSAGETEXT RECIPIENT DELIVERYDATE DELIVERYTIME CLIENT XMLREPLY Opzionale numero di telefono (max 16 cifre nella forma +39xxxxxxxxxx) o nome del mittente (max 11 caratteri alfanumerici). Per l invio di messaggi con personalizzazione del mittente è previsto un sovrapprezzo di 0,020 Euro/cad. Obbligatorio definisce il tipo di messaggio da inviare Obbligatorio testo del messaggio (max 160 caratteri) o dati per logo/suoneria Obbligatorio il numero del destinatario che riceverà il messaggio SMS (nella forma +39xxxxxxxxxx) Non ancora implementato specifica la data di consegna del messaggio Non ancora implementato specifica l'ora di consegna del messaggio Opzionale associa un nome/codice al messaggio in modo che il cliente possa creare rendiconti differenziati per cliente. Opzionale specifica se si vuole la risposta in XML o testo semplice USERNAME AND PASSWORD Questi due parametri identificano l account a cui verrà addebitato il costo per l invio attraverso il gateway. USERNAME contiene il nome utente e PASSWORD contiene la password ORIGINATOR Il mittente può essere numerico o alfanumerico. Se corrisponde al numero di telefono non deve superare i 16 caratteri e deve essere conforme al formato internazionale (es ). Se è una stringa alfanumerica deve essere lunga da 1 a 11 caratteri. I caratteri devono essere inviati nella codifica ISO8859-1; non sono ammessi caratteri Unicode. L'impostazione del mittente ha effetto esclusivamente per i messaggi di testo e i messaggi flash MESSAGETYPE Definisce il tipo di messaggio da inviare. VALORE sms flh nol bmp / gif / jpeg rtttl midi DESCRIZIONE Messaggio di testo. Messaggio flash. Logo operatore in formato NOL (7 bit). Il logo deve avere larghezza 72 pixel, altezza 14 pixel. Logo operatore o screensaver in formato BMP, GIF o JPEG (8 bit). Il logo deve avere larghezza 72 pixel e altezza 14 pixel, mentre lo screensaver largezza 72 pixel e altezza 28 pixel. Entrambi devono essere convertiti in formato esadecimale. Suoneria in formato RTTTL (7 bit). Suoneria in formato MIDI (8 bit). La suoneria deve essere convertita in formato esadecimale MESSAGETEXT Un messaggio di testo o flash non deve superare i 160 caratteri; non ci sono limiti invece per immagini e suonerie. I caratteri devono essere inviati nella codifica ISO8859-1; non sono ammessi caratteri Unicode RECIPIENT Ogni destinatario deve contenere il numero del terminale GSM e deve essere conforme al formato internazionale: Codice nazione (es. +39 per l italia) Prefisso dell operatore (es. 338, 335, 349) Numero del destinatario (es ) Questi campi combinati devono formare il numero del terminale GSM del destinatario (es ). Invii a più destinatari, fino ad un massimo di 200, possono essere effettuati separando i numeri di telefono con il carattere ; (punto e virgola).

4 Per effettuare test di invio senza che il messaggio SMS venga inviato è necessario inserire +0 come numero di cellulare destinatario DELIVERYDATE (non ancora implementato) Richiesta solo per l invio di messaggi ad una specifica data. Il formato data deve essere inviato nella forma giorno/mese/anno e deve essere uguale o successivo alla data di invio della chiamata CGI al gateway. ATTENZIONE: Se non viene indicato nulla nel campo DELIVERYDATE il messaggio viene consegnato immediatamente DELIVERYTIME (non ancora implementato) Richiesto per l invio di messaggi ad una specifica ora. Il formato deve essere del tipo hh:mm:ss Esempio: 23:19:00 (hh:mm:ss) ATTENZIONE: Se non viene indicato nulla nel campo DELIVERYTIME il messaggio viene consegnato immediatamente CLIENT E possibile assegnare un nome identificativo al messaggio o ai messaggi inviati compilando questo campo. In fase di visualizzazione dello storico degli invii effettuati sarà possibile filtrare i messaggi in base a questo parametro XMLREPLY E possibile scegliere se ricevere il messaggio di risposta in XML o in testo semplice. Assegnare a questo parametro il valore 1 per XML e 0 per testo semplice. In sua assenza il messaggio di risposta sarà coerente con la modalità di invio dei dati STRUTTURA DEI DATI XML L esempio seguente mostra come costruire una pacchetto di dati XML: <?xml version="1.0"?> <SMSMessage> <SMSAuthentication> <Username>nomeutente</Username> <Password>password</Password> </SMSAuthentication> <SMSMessageData> <Originator>Marco</Originator> <MessageType>sms</MessageType> <MessageText>Testo del messaggio</messagetext> <Recipient> </Recipient> <DeliveryDate></DeliveryDate> <DeliveryTime></DeliveryTime> <Client></Client> </SMSMessageData> <SMSReply> <XMLReply>1</XMLReply> </SMSReply> </SMSMessage> STATUS DI CONSEGNA In risposta all invio di un pacchetto XML al gateway SMS si riceverà una risposta con il risultato dell operazione di invio del messaggio.

5 <?xml version="1.0"?> <SMSMessage> <SMSGateway> <Response>0</Response> <TransactionID>a9bca4324c864d58a00e5831a83526b1</TransactionID> <ErrorText></ErrorText> </SMSGateway> </SMSMessage> Il tag <SMSMESSAGE> definisce l inizio e la fine della struttura dati XML. Il tag <SMSGATEWAY> definisce l inizio e la fine della risposta del gateway. All interno dei tag si trova un elemento intitolato <RESPONSE> che include il codice di risposta del gateway in relazione al pacchetto dati XML inviato (nella tabella 1 si trovano i codice di risposta). Il tag <TRANSACTIONID> definische l inizio e la fine del codice di tranzazione relativo all operazione di invio. Il tag <ERRORTEXT> include eventuali errori o commenti riportati dal gateway. Se si è scelto di ricevere la risposta in formato testo semplice, questa avrà la seguente forma: Response:0 TransactionID:39108e040a8c741ab1455d5f3fe88c0e ErrorText: 2.3. INVIO DEI DATI XML Connettendosi al gateway SMS (fare riferimento alla sezione 2.1), l applicazione può inviare dati XML al gateway SMS. Nota bene: nel testo seguente il carattere = a capo (codice ASCII 13) seguito da un line feed (codice ASCII 10) INVIO TRAMITE POST L invio dei messaggi SMS può essere effettuato con un POST della struttura dati XML all indirizzo: POST /send.php HTTP/1.0 Host: sms.kyron.it Connection: Keep-Alive Content-Type: application/x-www-form-urlencoded Content-Length: <Content-Length> XML=xmlpacket Oppure è possibile inviare ogni elemento XML come un campo del form separato: POST / send.php HTTP/1.0 Host: sms.kyron.it Connection: Keep-Alive Content-Type: application/x-www-form-urlencoded Content-Length: <Content-Length> username=<myusername>&password=<mypassword>&originator=<myoriginator>&messagetype=< mymessagetype>&messagetext=<mymessagetext>&recipient=<myrecipient>&deliverydate=<mydel iverydate>&deliverytime=<mydeliverytime>&client=<myclient>

6 2.3.2 INVIO TRAMITE GET Un altra alternativa per l invio di messaggi SMS è di chiamare l URL del gateway inviando i parametri in GET all interno dell URL: Originator>&messagetype=<myMessageType>&messagetext=<myMessageText>&recipient=<myReci pient>&deliverydate=<mydeliverydate>&deliverytime=<mydeliverytime>&client=<myclient> HTTP/1.0 Host: sms.kyron.it Connection: Keep-Alive ESEMPI Un semplice esempio di un form che invierà i dati XML al gateway SMS al click sul bottone submit: <form action=" method="post"> <textarea cols="70" rows="15" name="xml"> <?xml version="1.0"?> <SMSMessage> <SMSAuthentication> <Username>myusername</Username> <Password>mypassword</Password> </SMSAuthentication> <SMSMessageData> <Originator>mysender</Originator> <MessageType>sms</MessageType> <MessageText>mytext</MessageText> <Recipient> </Recipient> <DeliveryDate></DeliveryDate> <DeliveryTime></DeliveryTime> <Client></Client> </SMSMessageData> <SMSReply> <XMLReply>1</XMLReply> </SMSReply> </SMSMessage> </textarea> <input type="submit" value="submit"> </form> E anche possibile inviare i dati in campi singoli con gli stessi nomi dei campi XML

7 <form action=" method="post"> <table align ="center" cellspacing="2" cellpadding="2"> <td>username</td> <td><input type="text" name="username" value="myusername"></td> <td>password</td> <td><input type="text" name="password" value="mypassword"></td> <td>originator</td> <td><input type="text" name="originator" value="mysender"></td> <td>message Type</td> <td><input type="text" name="messagetype" value="sms"></td> <td>message Text</td> <td><input type="text" name="messagetext" value="mytext"></td> <td>recipient</td> <td><input type="text" name="recipient" value=" "></td> <td>delivery Date</td> <td><input type="text" name="deliverydate" value=""></td> <td>delivery Time</td> <td><input type="text" name="deliverytime" value=""></td> <td>client</td> <td><input type="text" name="client" value=""></td> <td>xml Reply</td> <td><input type="checkbox" name="xmlreply" value="1"></td> <td colspan=2 align=right> <input type="submit" value="submit"></td> </table> </form> 2.4. CODICI DI RITORNO Il gateway SMS rimanderà all applicazione che avrà effettuato la chiamata un codice di ritorno formato da un massimo di 2 cifre. Questi gli attuali codici di ritorno: 00 OK; Il messaggio è stato accettato dal server 99 Utente o password non accettati 98 Credito non sufficiente per la consegna dei messaggi SMS 97 Parametro CGI non supportato 96 Numero destinatario invalido 95 Formato dei parametri invalido 94 Servizio temporaneamente non disponibile 3. ACCESSO AL GATEWAY TRAMITE CLIENT DI POSTA ELETTRONICA Per poter trasmettere richieste di invio SMS alla nostra piattaforma tramite client di posta elettronica il cliente dovrà inviare un messaggio di testo (non HTML) al dominio sms.kyron.it.

8 Dopo pochi istanti il cliente riceverà un' di risposta contenente la conferma dell'avvenuta transazione oppure un messaggio di errore. In caso di errore l'utente non dovrà riprovare a mandare il messaggio che ha dato il risultato negativo; in questo caso il nostro gateway ha ricevuto il messaggio ma non è stato in grado di consegnarlo e qualsiasi ulteriore tentativo verrà rifiutato con il medesimo errore PARAMETRI DI INVIO Al contrario del gateway HTTP, tramite client di posta elettronica è possibile inviare solamente messaggi SMS standard (no flash/loghi/suonerie) e ad un unico destinatario. Di seguito i parametri da inserire all'interno del messaggio di posta: HEADER ELEMENTO FROM TO SUBJECT DESCRIZIONE Obbligatorio username del cliente cui verrà addebitato il costo dell operazione Obbligatorio il numero del destinatario che riceverà il messaggio SMS (nella forma +39xxxxxxxxxx) seguito dal dominio sms.kyron.it Opzionale - numero di telefono (max 16 cifre nella forma +39xxxxxxxxxx) o nome del mittente (max 11 caratteri alfanumerici) BODY ELEMENTO PASSWORD TEXT DESCRIZIONE Obbligatorio password del cliente Obbligatorio testo del messaggio (max 160 caratteri) FROM Il mittente del messaggio di posta elettronica deve corrispondere all'account abilitato per inviare SMS TO Il destinatario del messaggio di posta elettronica deve contenere il numero telefonico del terminale GSM nel formato internazione, a cui va aggiunto il dominio sms.kyron.it (es @sms.kyron.it) SUBJECT Il mittente può essere numerico o alfanumerico. Se corrisponde al numero di telefono non deve superare i 16 caratteri e deve essere conforme al formato internazionale (es ). Se è una stringa alfanumerica deve essere lunga da 1 a 11 caratteri PASSWORD La prima riga del messaggio deve contenere la password di accesso dell'utente, preceduta dalla stringa Password: (senza virgolette) TEXT Il resto del corpo del messaggio è riservato per il testo da inviare via SMS e non deve superare i 160 caratteri. 3.2 ESEMPIO Un semplice esempio di che invierà i dati al gateway SMS:

9 From: myusername MIME-Version: 1.0 To: Subject: mysender Content-Type: text/plain; charset=iso ; format=flowed Content-Transfer-Encoding: 7bit Password: mypassword My message! E il relativo messaggio di risposta: Subject: SMS Status notification Content-Type: text/plain; From: Servizio SMS Kyron <sms@kyron.it> Sender: Servizio SMS Kyron <sms@kyron.it> To: myusername SMS inviato con successo Da: mysender A: Transazione: 8857b7410df f a9d Testo: My message! -- Servizio SMS Kyron di Maki S.r.l. Per ulteriori informazione inviate un messaggio a supporto@kyron.it 4. ESEMPI DI SCRIPT PER ACCEDERE AL GATEWAY Di seguito forniamo degli esempi di codice HTML, PHP e ASP che possono essere utilizzati, con poche modifiche, per accedere al gateway SMS Kyron tramite applicazioni sviluppate nei suddetti linguaggi di programmazione HTML Esempio di pagina HTML per inviare sms, loghi e suonerie a un singolo destinatario:

10 <!doctype html public "-//W3C//DTD HTML 4.0 //EN"> <html> <head> <title>invio SMS</title> </head> <body> <form action="<script>" method="post"> <table align="center" cellspacing="2" cellpadding="2"> <td>originator</td> <td><input type="text" name="originator" value="mysender"></td> <td>message Type</td> <td><select name="messagetype"> <option selected>sms</option> <option>flh</option> <option>nol</option> <option>bmp</option> <option>gif</option> <option>jpeg</option> <option>rtttl</option> <option>midi</option> </select></td> <td>message Text</td> <td><input type="text" name="messagetext" value="mytext"></td> <td>recipient</td> <td><input type="text" name="recipient" value=" "></td> <td colspan="2" align="right"> <input type="submit" value="submit"></td> </table> </form> </body> </html> L'unico campo da personalizzare è quello contrassegnato con <script>, che dovrà puntare a uno dei seguenti script PHP o ASP PHP Esempio di script PHP per effettuare il parsing dei campi del form ed inviare la richiesta al gateway SMS:

11 <?php // variabili da personalizzare $username = "myusername"; // nome dell'account $password = "mypassword"; // password dell'account $url = " // url del gateway // esempio di utilizzo della funzione sms() $response = sms($username, $password, $url); if ($response === FALSE) echo "Impossibile collegarsi al gateway."; else { if ($response[0] == "0") echo "Messaggio inviato (TransactionID = $response[1])"; else echo "Messaggio non inviato (ErrorText = $response[1])"; // codice per l'invio dei dati al gateway SMS Kyron function sms($username, $password, $url) { $data = "username=". urlencode($username). "&password=". urlencode($password); if (!empty($_request["originator"])) $data.= "&originator=". urlencode($_request["originator"]); $data.= "&messagetype=". urlencode($_request["messagetype"]); $data.= "&messagetext=". urlencode($_request["messagetext"]); $data.= "&recipient=". urlencode($_request["recipient"]); $data.= "&xmlreply=0"; $reply = send($url, $data); if ($reply!== FALSE) { $rows = explode("\n", $reply); $response = explode(":", $rows[0]); $transactionid = explode(":", $rows[1]); $errortext = explode(":", $rows[2]); if ($response[1] == "0") { return array($response[1], $transactionid[1]); else { return array($response[1], $errortext[1]); else return FALSE; function send($url, $data) { $link = curl_init(); curl_setopt($link, CURLOPT_URL, " curl_setopt($link, CURLOPT_HEADER, 0); curl_setopt($link, CURLOPT_POST, 1); curl_setopt($link, CURLOPT_RETURNTRANSFER, 1); curl_setopt($link, CURLOPT_POSTFIELDS, $data); $response = curl_exec($link); curl_close($link); return $response;?> Le due variabili da personalizzare sono $username e $password ASP Esempio di pagina HTML per inviare sms, loghi e suonerie a un singolo destinatario:

12 LCID = 1033%> <% // inizio variabili di configurazione var username="myusername"; //nome dell'account var password="mypassword"; //password dell'account var url = " // url del gateway Kyron // fine variabili di configurazione /* funzione sendsm(originator, messagetype, messagetext, recipient,username,password) in caso di successo ritorna il transaction ID relativo all'operazione di invio effettuata */ var inviosms = sendsms(new String(Request("originator")),new String(Request("messagetype")),new String(Request("messagetext")),new String(Request("recipient")), username, password); if (inviosms[0] == "0") { Response.write ("Inviato con successo. TransactionID:" + inviosms[1]); else { Response.write ("Errore:" + inviosms[1]); Response.write(invioSMS); // funzione sendsms function sendsms(originator,messagetype,messagetext,recipient) { url+= "?messagetype=" + Server.urlEncode(messagetype); url+= "&originator=" + Server.urlEncode(originator); url+= "&recipient=" + Server.urlEncode(recipient); url+= "&messagetext=" + Server.urlEncode(messagetext); url+= "&username=" + username; url+= "&password=" + password; url+= "&xmlreply=1"; // per ottenere risposta dal gateway in formato XML //creazione oggetto WinHttp var Http = Server.CreateObject("WinHttp.WinHttpRequest.5.1"); //chiamata al gateway HTTP Kyron try { Http.open ("GET", url, false); Http.send(); catch(e) { Response.write("<strong>Errore nella chiamata URL:</strong> " + url); Response.write(e.number & 0xFFFF); Response.write(e.description); xmldoc = new ActiveXObject("Msxml2.DOMDocument.4.0"); xmldoc.loadxml(http.responsetext); var ReturnCode = xmldoc.getelementsbytagname("response"); %> var TransactionID = xmldoc.getelementsbytagname("transactionid"); var ErrorText = xmldoc.getelementsbytagname("errortext"); this.xmldoc = null; var Http = ""; //parserizzazione del risultato ottenuto dal gateway SMS if (TransactionID.item(0).text!= "") { var arr_return = new Array(ReturnCode.item(0).text,TransactionID.item(0).text); else { var arr_return = new Array(ReturnCode.item(0).text,ErrorText.item(0).text); return(arr_return); Le due variabili da personalizzare sono username e password BIN2HEX Esempio di applicazione HTML/PHP per convertire un file binario in formato esadecimale, utile per inviare suonerie e loghi ad 8 bit. Pagina di upload del file:

13 <!doctype html public "-//W3C//DTD HTML 4.0 //EN"> <html> <head> <title>bin2hex</title> </head> <body> <form enctype="multipart/form-data" action="bin2hex.php" method="post"> Convert this file: <input name="media" type="file" /> <input type="submit" value="send File" /> </form> </body> </html> Script per la conversione: <?php if (is_uploaded_file($_files['media']['tmp_name'])) echo strtoupper(bin2hex(file_get_contents($_files['media']['tmp_name'])));?>