Documento: smsbatch.pdf Data ult. rev.:01/12/2008 Versione: 2.3 Destinatari: programmatori / sistemisti Indirizzo Gateway FTP : smsftp.titisms.it Porta : 21 Idle Timeout : 15 minuti Parametri tecnici per il collegamento al gateway SMS FUNZIONAMENTO Il gateway SMS di SMS Pubblicità supporta la spedizione batch di messaggi SMS. La spedizione avviene trasferendo un file dati ed un file comandi nell'area di spool associata all' account assegnato all' utente. I file dati e i file comandi devono essere realizzati come descritto nella sezione : FILE DATI E FILE COMANDI. Attualmente e' supportato il file transfer via ftp. L'area FTP di un account abilitato per le spedizioni batch possiede le seguenti tre directory : incoming/ Directory nella quale saranno trasferiti il file dati ed il file comandi, secondo la sequenza riportata nella sezione: TRASFERIMENTO FILE reports/ Directory nella quale saranno salvati i file dei reports delle spedizioni precedentemente effettuate. Il file sarà in formato ASCII ed internamente i file saranno strutturati come descritto nella sezione: I REPORTS notify/ Directory nella quale saranno salvate le liste delle notifiche di avvenuta ricezione dei messaggi. I file saranno strutturati come descritto nella sezione: LE NOTIFICHE ------------------------------------------------------------------------------------------------------------------------------------------------------------ FILE DATI E FILE COMANDI Il file dati può essere in formato ASCII o in formato xbase (dbiii). Il gateway riconosce come file ASCII tutti i file che non hanno estensione ".dbf". Questi ultimi vengono trattati come file in formato xbase. FORMATTAZIONE FILE DATI : Ogni riga del file andrà a contenere un unico messaggio. Il record o riga sarà suddivisa in campi. File a formato fisso, lunghezza riga: 242 caratteri esclusa la terminazione di riga: LineFeed (0xA) primo campo : nome: rcpt_num descr: numero telefonico del destinatario offset: 0 (non utilizzato nel formato XBASE) lunghezza: 25 (non utilizzato nel formato XBASE) formato +CCOOOTTTTTTT... CC = country code, OOO = prefisso operatore, TTTTTT.. = numero cellulare INFO : (padding non utilizzato nel formato XBASE) il campo deve essere allineato a sx padding da dx con carattere ' ' (0x20) esempio : +393281234702 secondo campo : nome: from_str descr: id del generante (mittente del messaggio) offset: 25 (non utilizzato nel formato XBASE) lunghezza: 25 (non utilizzato nel formato XBASE) formato: alfanumerico o numero in formato internazionale Es. Alpha: Mittente Es. Num : 00393211234567 oppure +393211234567 INFO: (padding non utilizzato nel formato XBASE) il campo deve essereallineato a sx padding da dx con carattere ' ' (0x20).
In presenza di mittente alfanumerico la sua lunghezza non deve superare gli 11 caratteri. In presenza di mittente numerico la sua lunghezza non deve superare le 17 cifre (oppure 16 più il carattere + all'inizio) terzo campo: nome: body descr: corpo del messaggio offset: 50 (non utilizzato nel formato XBASE) lunghezza: 160 (non utilizzato nel formato XBASE) formato: alfanumerico INFO : (padding non utilizzato nel formato XBASE) il campo deve essere allineato a sx padding da dx con carattere ' ' (0x20). quarto campo: nome: expire descr: validità, in ore, del messaggio offset: 210 (non utilizzato nel formato XBASE) lunghezza: 10 (non utilizzato nel formato XBASE) formato: intero ascii esempio: ignorare le virgolette "0000000048" INFO: (padding non utilizzato nel formato XBASE) il valore di expire non è garantito, la sua validità cambia in base al fornitore utilizzato. Il tempo di vita di un messaggio per default è di 48 ore. Il campo in questione è stato mantenuto per conformità con le specifiche precedenti. quinto campo: nome: quality descr: qualità del messaggio offset: 220 (non utilizzato nel formato XBASE) lunghezza: 2 (non utilizzato nel formato XBASE) formato: char (lowercase) esempi: ignorare apici, 'h ' oppure 'll' INFO: (padding non utilizzato nel formato XBASE) il campo deve essere allineato a sx padding a dx con carattere ' ' (0x20). Nel caso in cui non venga specificato alcun valore sarà utilizzato il default value riportato di seguito. Valori possibili: (ignorare gli spazi per il formato XBASE) ll Qualità Bassa l Qualità Media h Qualita Alta a Qualità Automatica (valore di default) sesto campo: nome: act descr: identificativo del messaggio offset: 222 (non utilizzato nel formato XBASE) lunghezza: 20 (non utilizzato nel formato XBASE) formato: int esempio: '1234567901234567890' oppure '1234567 ' (ignorare gli spazi nel formato XBASE) INFO: (padding non utilizzato nel formato XBASE) il campo deve essere allineato a sx padding a dx con carattere ' ' (0x20). In presenza del parametro act, la spedizione del singolo messaggio sarà considerata come spedizione in qualità alta con notifica. ------------------------------------------------------------------------------------------------------------------------------------------------------------
Il limite massimo di SMS che si possono inserire in un file di dati, affinchè venga correttamente processato, è di 25.000 NOTE UTILI: Per la creazione del file ASCII, ogni record può essere generato seguendo questa formattazione C-like : record = "%-25s%-25s%-160s%010d%-2s%-20s\n", rcpt_num, from_str, body, expire, quality, act IL FILE COMANDI : Il file comandi conterrà delle istruzioni utili per interagire con il gateway SMS. Per maggiori informazioni su come configurare il file comandi consultare la sezione ISTRUZIONI FILE COMANDI. TRASFERIMENTO FILE La sequenza di trasferimento è molto importante, prima deve essere trasferito il file dati e solo successivamente il file comandi. Quest ultimo è necessario per segnalare al gateway che il file dati è stato trasferito interamente. Il file comandi deve avere lo stesso nome del file dati, ma con estensione aggiuntiva ".do_send". Esempio : per il file dati "sms.txt", il relativo file comandi sarà "sms.txt.do_send" Il sistema di elaborazione dei file dati ha un numero massimo di processi che possono essere lanciati contemporaneamente, qualora il limite venga superato le richieste in eccesso verranno scartate ed i file rimarranno nella cartella incoming. Il consiglio è quello di effettuare spedizioni distaccate l'una dall'altra di almeno un minuto, in questo modo si ridurrà sensibilmente il verificarsi di queste situazioni. Qualora dovesse accadere che i file non vengano processati per un eccesso di processi attivi contemporaneamente la soluzione è semplice, basterà effettuare una GET di entrambi i file e successivamente ripetere due nuove PUT per reinoltrarli al sistema. ------------------------------------------------------------------------------------------------------------------------------------------------------------ I REPORTS Il file contenente il report della spedizione avrà un nome così formato: yyyymmdd-hhmmss-name.txt Esempio : 20041014-131022-sms.txt La data e l'ora riportati nel nome del file, indicano la data e l'ora di spedizione. Struttura interna di un file di report: Ogni file di report al suo interno sarà strutturato da righe formate nel seguente modo : I possibili TAG sono : MSG La sua descrizione conterrà un messaggio generico. MSG: begin TAG: DESCRIZIONE BILL La sua descrizione conterrà il costo applicato al singolo messaggio con il numero di linea corrispondente, seguito dal numero di telefono a cui è stato spedito il messaggio. BILL: 590 at line 1 for +393101111212 ERR La sua descrizione conterrà l'errore verificatosi all'atto della spedizione del messaggio indicato dal numero di riga che segue il codice d'errore. Codici riportati nella sezione CODICI DI ERRORE ERR: KO 211 quota_abs reached at line 1 (no credit) INFO La sua descrizione conterrà delle informazioni riguardo la spedizione appena eseguita.
INFO: Processed 2 record(s) Il file di report sarà formattato, per default con i TAG in questa sequenza : TAG -> MSG: TAG -> BILL: or ERR: TAG -> INFO: TAG -> MSG: -- Inizio file d'esempio MSG: begin BILL: 590 at line 1 for +393101162011 BILL: 600 at line 2 for +393211222021 BILL: 600 at line 3 for +393121214020 BILL: 600 at line 4 for +393102210212 BILL: 600 at line 5 for +393221221121 INFO: Processed 5 record(s) MSG: end -- Fine file d'esempio Il cliente puo decidere arbitrariamente la formattazione del file di report generato dal gateway SMS. Vedere la sezione ISTRUZIONI FILE COMANDI di seguito. NOTE UTILI : IMPORTANTE:La sequenza dei TAG : BILL ed ERR non avrà obbligatoriamente la stessa sequenza dei messaggi inseriti all'interno del file dati, soprattutto in presenza di file dati corposi. Questo è dovuto al processo di ottimizzazione pre spedizione effettuato dal gateway sms. Nella formattazione di default all'interno del report ogni parola sarà sempre separata dalla successiva da un solo ed unico spazio (carattere 0x20). ISTRUZIONI FILE COMANDI Il file comandi può essere completamente vuoto oppure contenere istruzioni che permettono l'interazione con il gateway SMS. Nel caso in cui sia vuoto, la sua presenza attiverà esclusivamente la spedizione dei/l messaggi/o contenuti/o nel file dati. Ogni comando presente all'interno del file deve essere un'associazione del tipo : PARAMETRO = VALORE Un file comandi può essere suddiviso in due sezioni nel seguente ordine: Variabili Azioni I commenti: All'interno del file comandi è possibile inserire dei commenti. Ogni riga che inizia con carattere # (cancelletto) o \\ sarà considerata come un commento e quindi ignorata. ############ #questo è un commento #di esempio ################## \\questo è un altro commento \\\\\\\\\\\\\\\di esempio ------------------------------------------------------------------------------------------------------------------------------------------------------------ Le variabili: Ogni associazione: parametro -> valore, presente sopra la dichiarazione delle azioni, sarà preso in considerazione come dichiarazione di una variabile. Esempio di variabili: var1= valore della variabile URL = http://www.example.com/cgi.pl NomeAzienda = EXAMPLE
Nel caso in cui si vogliano utilizzare degli spazi all'interno di un valore di una variabile, è necessario racchiudere il contenuto del valore tra apici o virgolette (non backtick) : var1='valore con spazi' var2= valore con spazi. Nel caso in cui una stringa con spazi non venga racchiusa tra i caratteri sopra riportati, il sistema utilizzerà come valore da associare alla variabile (o al comando) il testo presente dopo l'associazione, fino al primo spazio escluso. Per richiamare nelle sezioni successive le variabili sopra indicate, si dovrà utilizzare il carattere $ (dollaro) prima del nome della variabile. Esempio di associazione utilizzando le variabili: PARAMETRO1=$var1 PARAMETRO2=$URL PARAMETRO3=$NomeAzienda I nomi delle variabili sono case sensitive ($var1 è diverso da $VAR1 che sarà a sua volta diverso da $var1) Una variabile può far riferimento al valore di un'altra variabile per una sola volta. Esempio : var1= valore variabile var2=$var1 non sarà possibile: var3=$var2 in quest'ultimo caso di associazione sarà preso in considerazione come valore della variabile il nome della variabile associata, escluso il carattere dollaro. Nell'esempio sopra, quindi, il valore di $var3 sarà var2. Le azioni: Le azioni possibili da richiamare sono due : ALERT Attraverso quest'azione sarà possibile settare i comandi che fanno riferimento agli alert che è possibile ricevere al termine di ogni spedizione. Gli alert di fine spedizione batch implementati attualmente sono: POST HTTP, E-Mail, SMS. INFO Attraverso quest'azione sarà possibile impartire comandi che fanno riferimento al settaggio di informazioni utili alla spedizione che si sta andando ad effettuare, o comandi utili alla richiesta di informazioni su spedizioni precedentemente effettuate (vedi Notifiche). Prima di iniziare ad impartire comandi inerenti ad un'azione, è necessario dichiarare l'azione stessa. Un'azione va dichiarata utilizzando il comando ACTION : ACTION=NOME-AZIONE ACTION=ALERT...comandi per alert... ACTION=INFO...comandi per info... Ogni azione è a sua volta suddivisa in subazioni. Per ogni subazione è possibile utilizzare uno specifico SET DI COMANDI. Di seguito sono riportati i comandi associati ad ogni azione e relativa subazione.
Set di comandi: Comandi associati all'azione ALERT : Subazione ALERT_WEB: ALERT_WEB Può contenere valore on o valore off, attiverà o disattiverà l'alert via web. In presenza di un valore differente da on, sarà utilizzato per default il valore off e in questo caso i comandi presenti di seguito, fino ad una nuova subazione attiva, non saranno presi in considerazione. #attiva alert attraverso POST HTTP. ALERT_WEB = on URL Il valore da associare sarà un URL verso il quale saranno effettuate le POST HTTP di notifica avvenuta spedizione. L'URL non potrà superare lunghezza 255. URL=http://www.example.com/cgi-batch/endbatch.php Info: I parametri che dovrà accettare in ingresso sono i seguenti: account conterrà la login dell'account per il quale è stata effettuata la spedizione. ticket conterrà il valore associato al comando TICKET come descritto di seguito. reportpath indica il path completo del report da scaricare via FTP come descritto di seguito nella sezione NOTIFICA AVVENUTA SPEDIZIONE. reportname indica il solo nome del report da scaricare via FTP come descritto di seguito nella sezione NOTIFICA AVVENUTA SPEDIZIONE. 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. TICKET Il valore da associare sarà una stringa alfanumerica di lunghezza massima 255. Potrà quindi contenere esclusivamente caratteri compresi nell'insieme [A-Za-z0-9]. Il valore associato al comando TICKET sarà reinoltrato al cliente così come è stato inserito all'interno del file comandi. TICKET=1223111 TICKET=P4sSw0rd E' consigliabile utilizzare il valore associato al comando, come un ticket condiviso tra client e gateway SMS o anche come identificativo della spedizione. Esempio di file comandi : ACTION=ALERT ALERT_WEB=on URL=http://www.example.com/cgi-bin/alertme.cgi TICKET=ID122334455
Subazione ALERT_PHONE: ALERT_PHONE Può contenere valore on o valore off, attiverà o disattiverà l'alert via SMS. In presenza di un valore differente da on, sarà utilizzato per default il valore off e in questo caso i comandi presenti di seguito, fino ad una nuova subazione attiva, non saranno presi in considerazione. #attiva alert attraverso SMS. ALERT_PHONE = on PHONE Il valore da associare sarà una stringa che conterrà il numero destinatario dell'sms di alert. Il numero deve essere nel formato internazionale. Di lunghezza massima 17. Esempio : PHONE=+393341122112 OADC Il valore da associare sarà una stringa alfanumerica che non dovrà superare lunghezza 11 caratteri. Sarà possibile inserire esclusivamente caratteri compresi nell'insieme [A-Za-z0-9\s] oppure un numero telefonico nel formato internazionale OADC= Mittente OADC= +393401122112 OADC= 00393331122112 QUALITY Il valore da associare sarà una stringa di massimo 2 lettere, che indicherà la qualità del messaggio SMS, che il gateway SMS inoltrerà come alert. I valori possibili sono quelli descritti nella sezione formattazione file dati riguardo il quinto campo. L'unica differenza è che in questo caso il suo valore sarà case insensitive. QUALITY=h QUALITY=A I messaggi SMS saranno inoltrati utilizzando il credito dell'account che ha effettuato la spedizione batch. Il testo del messaggio SMS sarà in lingua italiana. Esempio di file comandi : ACTION=ALERT ALERT_PHONE=on PHONE=+393221112088 QUALITY=H OADC="SMS ALERT" Esempio di file comandi con doppio alert : ACTION=ALERT ALERT_PHONE=on PHONE=+393221112088 QUALITY=H OADC="SMS ALERT" ALERT_WEB=on URL=http://www.example.com/cgi-bin/alertme.cgi TICKET=ID122334455
Esempio di file comandi con doppio alert ed uno ad off : ACTION=ALERT ALERT_PHONE=off PHONE=+393221112088 QUALITY=H OADC="SMS ALERT" ALERT_WEB=on URL=http://www.example.com/cgi-bin/alertme.cgi TICKET=ID122334455 In questo caso l'sms di alert non sarà inoltrato. Subazione ALERT_EMAIL: ALERT_EMAIL Può contenere valore on o valore off, attiverà o disattiverà l'alert via E-Mail. In presenza di un valore differente da on, sarà utilizzato per default il valore off e in questo caso i comandi presenti di seguito, fino ad una nuova subazione attiva, non saranno presi in considerazione. ALERT_EMAIL=on FROM Il valore da associare sarà l'indirizzo del mittente della mail. L'indirizzo del mittente dovrà rispettare lo standard user@domain.tld All'interno dell'indirizzo non dovranno essere presenti metacaratteri, oltre i caratteri compresi in [_-.]. FROM=sms@example.com Nel caso in cui non venga utilizzato alcun valore sarà settato per default il valore fittizio sms@sms.tld CC Come il comando FROM Per default il suo valore è nullo. BCC Come il comando FROM Per default il suo valore è nullo. BODY Il valore da associare al comando identificherà il formato del corpo dell'e-mail che si andrà a ricevere. Potrà assumere due valori : TEXT oppure HTML BODY=HTML Per default il suo valore è TEXT. Il testo della mail sarà in lingua italiana. Esempio di file comandi: ACTION=ALERT ALERT_PHONE=on PHONE=+393221112088 QUALITY=H
OADC="SMS ALERT" ALERT_WEB=off URL=http://www.example.com/cgi-bin/alertme.cgi TICKET=ID122334455 ALERT_EMAIL=on FROM=sms@example.com CC=alert@example.com BODY=HTML --fine file comandi--- In questo caso il gateway SMS andrà ad inviare un SMS di alert al termine della spedizione piu un mail in formato HTML diretta a i due indirizzi specificati nel comando FROM e CC. Comandi associati all'azione INFO : Subazione GET_NOTIFY: GET_NOTIFY Può contenere valore on o valore off, attiverà o disattiverà il settaggio delle informazioni inerenti alla ricezione delle notifiche. In presenza di un valore differente da on, sarà utilizzato per default il valore off e in questo caso i comandi presenti di seguito, fino ad una nuova subazione attiva, non saranno presi in considerazione. GET_NOTIFY=on ACT Il comando può contenere valore all oppure un ACT precedentemente utilizzato nella spedizione di un messaggio con notifica di avvenuta ricezione. Settando il suo valore ad all, il gateway SMS andrà a prelevare tutte le notifiche presenti e andrà a formattare un file ASCII, salvandolo successivamente nella directory /notify come descritto nella sezione LE NOTIFICHE. Settando un ACT singolo, andrà ad effettuare una ricerca all'interno delle notifiche ricevute e ritornerà, se presente. ACT=all oppure ACT=121966096681 Il valore numerico dell'act singolo non deve superare lunghezza 20. REGEX Il comando può contenere un'espressione regolare per effettuare delle ricerche precise all'interno delle notifiche ricevute. Il suo valore non può superare lunghezza 10. Può contenere esclusivamente caratteri compresi nell'insieme [0-9.*] Esempio di criteri di ricerca: REGEX=11.* #In questo caso chiediamo al gateway SMS di ritornare tutte #le notifiche richieste che hanno un ACT che inizi per 11 #seguito da qualsiasi altra cifra REGEX=.*12196.* #Tutte le notifiche che hanno per ACT un valore che contenga #all'interno le cifre 12196 ed inizi e termini per qualsiasi #cifra REGEX=12.*81 #Tutte le notifiche che hanno come ACT un valore che termina #per 81 ed inizi per 12 Note Tra il comando ACT ed il comando REGEX ha priorità il comando REGEX WHERE Il valore da associare al comando andrà ad identificare il protocollo da utilizzare per il trasferimento delle notifiche di avvenuta ricezione richieste nell'attuale spedizione batch. I valori possibili sono due : FTP o HTTP
WHERE=FTP WHERE=HTTP Nel caso in cui venga richiesto il protocollo HTTP, le notifiche saranno inoltrate singolarmente attraverso delle POST HTTP. Nel caso in cui venga settato FTP come protocollo, le notifiche dovranno essere richieste inoltrando un nuovo file dati (anche vuoto) e un nuovo file comandi, agendo sulla subazione GET_NOTIFY, come descritto nella sezione LE NOTIFICHE. Per default il valore del comando WHERE sarà FTP. Consultare la sezione LE NOTIFICHE presente di seguito. URLINFO Il valore da associare a questo comando sarà un URL che verrà richiamato dal gateway SMS attraverso una POST HTTP, al termine del processo di preparazione delle file ASCII contenete le notifiche SMS ricevute. URLINFO=http://www.example.com/cgi-batch/notifyinfo.cgi Info: I parametri che dovrà accettare in ingresso sono i seguenti account Conterrà la login dell'account per il quale è stata effettuata la richiesta. notify_tot Conterrà il numero di notifiche totali ricevute e ancora presenti sul gateway SMS. notify_get Conterrà il numero di notifiche ritornate dopo la richiesta. filename Conterrà il nome del file ASCII presente nella directory /notify sul gateway SMS nel quale sono state salvate le notifiche. path Conterrà il path completo del file ASCII contenente le notifiche. Consultare la sezione LE NOTIFICHE presente di seguito. La POST sarà effettuata solo ed esclusivamente in presenza di notifiche. Esempi di file comandi per invio di messaggi con notifica : ACTION=INFO GET_NOTIFY=on WHERE = FTP ACTION=INFO GET_NOTIFY=on WHERE = HTTP In quest'ultimo caso le notifiche dell'attuale spedizione saranno inoltrate direttamente attraverso delle POST HTTP all'url specificata all'atto dell'attivazione dell'account. Esempio di file comandi per richiesta di notifiche : ACTION=INFO GET_NOTIFY=on ACT=all URLINFO = http://www.example.com/batch/alertnotifybatch
Esempio di file comandi per richiesta di notifiche con REGEX : ACTION=INFO GET_NOTIFY=on REGEX=12.* URLINFO = http://www.example.com/batch/alertnotifybatch Non settando un URL attraverso il comando URLINFO, le notifiche saranno prelevate ad inserite nella directory /notify ugualmente. E' possibile richiedere delle notifiche di messaggi precedentemente inviati anche durante una nuova spedizione batch, combinando i comandi della subazione GET_NOTIFY. ACTION=INFO GET_NOTIFY=on #voglio che le notifiche attuali mi vengano inoltrate #direttamente attraverso HTTP WHERE=HTTP #allo stesso tempo desidero che il gateway SMS mi restituisca #le notifiche che ho richiesto di ricevere precedentemente via #FTP ACT=all URLINFO=http://www.example.com/notifyalert Subazione REPORTS: REPORTS Potrà contenere valore on o valore off. Utile per attivare o disattivare i comandi utili alla formattazione dei reports di spedizione. REPORTS=on INFO Può contenere un cifra che andrà ad indicare il livello di verbosità dei TAG INFO presenti nel file di report. I valori possibili sono : 0 Off. Disattiva completamente i TAG INFO. I TAG INFO non saranno presenti all'interno del file di report. 1 Low. Sarà presente un solo TAG INFO. Che indicherà il numero di record processati. (Come le versioni precedenti) 2 Medium. Saranno presenti 3 TAG INFO. Conterrano informazioni sulla spedizione effettuata (record processati, numero di errori, numero di messaggi inviati con successo). INFO=1 #valore di default (Low) Tutti i valori successivi [3-9] sono riservati per le versioni successive del sistema. Nel caso in cui venga settato un valore riservato il TAG INFO non verrà inserito all'interno del report (valore 0 Off).
ERR Potrà assumere valore on o off, attiva o disattiva il TAG ERR all'interno del file di report. Per default il suo valore è ad on. ERR=off #disattiva i TAG ERR all'interno del file di report per la #spedizione in corso MSG Potrà assumere valore on o off, attiva o disattiva il TAG MSG all'interno del file di report. Per default il suo valore è ad on. MSG=off #disattiva i TAG MSG all'interno del file di report per la #spedizione in corso BILL Potrà assumere valore on o off, attiva o disattiva il TAG BILL all'interno del file di report. Per default il suo valore è ad on. BILL=off #disattiva i TAG BILL all'interno del file di report, per la #spedizione in corso. I comandi di Formattazione dei Reports: Ogni DESCRIZIONE può essere suddivisa in 5 elementi informativi: un messaggio, un numero di riga, un numero di telefono e un'opzionale informazione aggiuntiva associata alla descrizione. Attraverso i comandi FORMAT* è possibile decidere la formattazione della DESCRZIONE e quindi decidere a priori la presenza degli elementi informativi all'interno della stringa. FORMATERR Il suo valore sarà una stringa che indica il formato utilizzato per la descrizione del TAG ERR, all'atto della creazione del report. La sua lunghezza non deve essere superiore a 50 caratteri. I caratteri che è possibile inserire all'interno della stringa, devono rientrare nell'insieme [a-za-z0-9%\s:-]. Nel caso in cui la stringa contenga caratteri non ammessi sarà utilizzato il suo valore di default. I caratteri di sostituzione sono : %m Message. Indica la presenza dell'elemento informativo Messaggio. %l Line. Indica la presenza dell'elemento informativo Linea. %n Number. Indica la presenza dell'elemento informativo Numero. %i Info. Indica la presenza dell'elemento informativo Informazione FORMATERR=%m at line %l -%n- FORMATERR=%n:%l:%m:%i FORMATERR=%n-%l FORMATERR=%m%%n%%l Il risultato sarà: nel primo esempio ERR: KO 301 at line 2 -+39338199112- nel secondo esempio ERR: +39338199112:2:KO 301: nel terzo esempio ERR: +39338199112-2
nel quarto esempio ERR: KO 301%+39338199112%2 FORMATBILL Il suo valore sarà una stringa che indica il formato utilizzato per la DESCRIZIONE del TAG BILL, all'atto della creazione del report. La sua lunghezza non deve essere superiore a 50 caratteri. I caratteri che è possibile inserire all'interno della stringa, devono rientrare nell'insieme [a-za-z0-9%\s:-]. Nel caso in cui la stringa contenga caratteri non ammessi sarà utilizzato il suo valore di default. I caratteri di sostituzione sono : %m Message. Indica la presenza dell'elemento informativo Messaggio. %l Line. Indica la presenza dell'elemento informativo Linea. %n Number. Indica la presenza dell'elemento informativo Numero. %i Info. Indica la presenza dell'elemento informativo Informazione FORMATBILL=%m at line %l -%n- FORMATBILL=%n:%l:%m:%i FORMATBILL=%n-%l FORMATBILL=%m%%n%%l Il risultato sarà: nel primo esempio BILL: OK 677 at line 2 -+39338199112- nel secondo esempio BILL: +39338199112:2:OK 677: nel terzo esempio BILL: +39338199112-2 nel quarto esempio BILL: OK 677%+39338199112%2 Una Descrizione non potrà mai superare lunghezza 150 caratteri. In presenza di piu caratteri di sostituzione uguali e ripetuti, solo ed esclusivamente la prima occorrenza sarà trattata come carattere di sostituzione, le restanti saranno considerate testo aggiuntivo. Esempio di file comandi: ACTION=INFO REPORTS=on INFO=1 MSG=off ERR=on BILL=on FORMATERR="M:%mL:%lN:%nI:%i" FORMATBILL= %m Phone Number %n Line %l ACTION=INFO REPORTS=on INFO=0 MSG=off BILL=off
ERR=on FORMATERR= %m-%n-%l In quest'ultimo esempio chiediamo al gateway di creare un file di report che contiene esclusivamente i TAG ERR ed una descrizione semplice da parsare, in cui ogni elemento informativo è separato dal successivo con un carattere - : MESSAGGIO-TELEFONO-NUMERO DI RIGA Un file di report possibile sarebbe: ---inizio file di report--- ERR: KO 301-+3931911134566-2 ERR: KO 302-+3931023411223-3 ---fine file di report--- LE NOTIFICHE La presenza del sesto campo act, all'interno del file ASCII o Dbf, indicherà la richiesta di notifica di avvenuta ricezione del messaggio associato all'act stesso. Le notifiche di avvenuta ricezione è possibile riceverle singolarmente attraverso il protocollo HTTP, con una POST effettuata dal gateway SMS verso un URL precedentemente indicato dal cliente, o in blocco attraverso il protocollo FTP, all'interno di un file ASCII situato nella directory notify/ come indicato sopra. La notifica ricevuta in questo caso è la mobile delivery notification, esattamente i dati ricevuti saranno, la data e l'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) Rejected by Operator I messaggi di mancata consegna variano in base all'operatore utilizzato. Ricezione HTTP : Le notifiche attraverso HTTP sono inoltrate dal gateway SMS con una POST HTTP (una POST per ogni notifica) ad un URL precedentemente indicato dal cliente all'atto dell'attivazione dell'account. 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 gg-mm-aaaa (Es.: 23-01-2003) Nel caso di mancata consegna del messaggio, il campo data sarà uguale a : 00-00-00
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. Ricezione FTP : Le notifiche di avvenuta ricezione possono anche essere richieste e ricevute attraverso il protocollo FTP. Per effettuare una richiesta di notifiche, si dovranno trasferire i file (dati e comandi) come descritto nella sezione TRASFERIMENTO FILE. Il risultato della richiesta, un file in formato ASCII contenente le notifiche ricevute, sarà inserito nella directory /notify del proprio account FTP. Il file ASCII conterrà per ogni riga una stringa che identifica un notifica ricevuta. La stringa sarà formata da tre campi separati da un carattere slash /. Struttura: ACT/DATE/TIME Il primo parametro è il valore ACT precedentemente assegnato al messaggio all'atto della spedizione, il secondo parametro è la data di consegna del messaggio, il terzo parametro è l'orario di consegna del messaggio. 12345/14-10-2004/10:51:26 In questo esempio l'act ha valore 12345 la data è : Giorno 14, Mese Ottobre, Anno 2004, alle ore 10:51:26. In presenza di una notifica di non consegna la struttura della stringa di notifica sarà : ACT/MOTIVO/errore 12311123/Unknown subscriber/errore Al termine di ogni stringa di notifica sarà presente un carattere Line Feed \n. In caso di errore, il campo TIME sarà sempre uguale ad errore. Potrebbe quindi essere utile effettuare prima un check del campo TIME se questo contiene la stringa errore il campo DATE conterrà il motivo della mancata consegna. Nel caso in cui il terminale mobile di destinazione non riesca a notificare all'smsc (Short Message Service Centre) la notifica di avvenuta ricezione del messaggio anche avendolo ricevuto correttamente, dopo 72 ore dalla spedizione il gateway SMS provvederà ad inoltrare una notifica di errore motivandola come : Delivery Notification Unavailable E' possibile ricevere un alert via HTTP al termine della generazione del file contenente le notifiche. Utilizzando il comando URLINFO come descritto sopra. Basterà quindi ricevere dal gateway SMS il path completo del file di notifiche generato ed effettuare una connessione FTP all' indirizzo smsftp.titisms.it porta 21. Attraverso il comando ftp : GET path_file_remoto nome_file_locale Sarà restituito il file contenente le notifiche. CODICI DI ERRORE Di seguito è riportata la lista dei codici di errore possibili (Il messaggio tra parentesi è solo una descrizione del messaggio di errore, presente per chiarezza) : Le stringhe riportate di seguito saranno l'elemento informativo messaggio della DESCRZIONE del TAG ERR. Gli errori batch si suddividono in errori in : Errori in fase di spedizione Errori in fase di preprocessing
Errori in fase di spedizione : KO 103 bad recipient KO 109 carrier problem KO 111 banned KO 211 quota_abs reached (termine del credito) KO 213 quota_ny reached (termine delle notifiche) KO 300 System (Internal Error) KO 301 (Connection Problem) KO 302 (Generic Error) KO 303 (Connection Problem) 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) Errori in fase di preprocessing: KO 110 Msg Blocked bad line length bad from bad number bad act bad body internal error 201