Principali caratteristiche piattaforma web ciaosms.it

Istruzioni Backoffice

Post get http

VERSION 2.1

CiaoSMS by Bitway Italia – Via Tommaso Fiore 1/K – 70015 Noci ( Bari ) – tel.080 222 12 16

Principali caratteristiche della piattaforma web ciaosms.it

Istruzioni per l’invio di sms tramite ciaosms.it con utilizzo di vostri applicativi connessi sul gateway sms

tramite chiamata post get http:

Documento: Istruzioni gateway sms - Post get http - backoffice.pdf

Versione: 2.1

Indice:

1 - Principali caratteristiche tecniche della piattaforma web ciaosms.it

2 - Invio singolo SMS tramite richiesta POST/GET HTTP

3 - Invio multiplo SMS tramite richiesta POST/GET HTTP

4 - Controllo Credito SMS rimanente tramite richiesta POST/GET HTTP

5 - Controllo stato Notifica tramite richiesta POST/GET HTTP

6 - Controllo stato Notifica Multipla per data, tramite richiesta POST/GET HTTP

7 - Ricezione delle Notifiche via POST HTTP

7.1 - Specifiche per la ricezione dei POST HTTP

8 - Invio multiplo richieste MNC tramite richiesta POST/GET HTTP

8.1 - Controllo stato MNC tramite richiesta POST/GET HTTP

1 - Principali caratteristiche tecniche della piattaforma web ciaosms.it

1) Accesso tramite Username e Password dedicate su pagina web, .accessibile da qualsiasi computer

collegato al web; 2) Possibilità di controllo del credito residuo in tempo reale sia in Euro che inSMS rimanenti;3) Possibilità di utilizzo della piattaforma web contemporaneamente da piùpostazioni connesse al web;4) possibilità di creare infiniti Gruppi (rubriche);5) possibilità di inserire all' interno di ogni gruppo infiniti contatti;6) invio Singolo sms;7) invio multiplo sms a tutti i gruppi contemporanemente dello stesso sms;8) invio multiplo sms solo al alcuni contatti del gruppo;9) possibilità di differire l'invio degli sms programmando data ed ora di invio;10) status monitor di invio sms aggiornato in tempo reale;11) statistiche di invio aggiornate in tempo reale ed esportabili in file formatoexcell;12) Creazione di infiniti modelli di invio ;13) Invio Programmato di auguri di compleanno con personalizzazione deltesto di auguri;14) Gestione delle rubriche in formato excell e formato di testo txt (notepad);15) Mittente dell'sms personalizzabile;16) Gestione su cartella dedicata delle notifiche di ricezione sms;17) Visualizzazione dello storico degli invii per data ed ora, numerodestinatario, testo sms inviato;18) Testo SMS da 160 caratteri + 11 caratteri per personalizzare il mittente.19) Servizio MNC (Multi Number Check) per verifica dei numeri di telefono20) SMS concatenati oltre i 160 caratteri.

Gli sms concatenati sono a multipli di 134 caratteri per singolo sms. E' possibile spedire testi lunghi fino a 804 caratteri ( 6 sms concatenati ) che il destinatario riceverà sul proprio telefono cellulare sotto forma di un UNICO messaggio SMS.

L’invio di sms avviene tramite richieste POST/http

2 - Invio singolo SMS tramite richiesta POST/GET HTTP

URL: http://login.ciaosms.it/sms/send.php Parametri

autenticazione:

· user – Login cliente· pass – Password cliente

Parametri obbligatori:

· rcpt – Numero destinatario nel formato internazionale %2bXXYYYZZZZZZZ

· data – Testo del messaggio (max 160 caratteri)

· sender – Mittente del messaggio (max 11 caratteri alfanumerici o numero%2bXXYYYZZZZZZZ)

· qty – Qualità del messaggio: (ll, a, n – bassa, automatica, notifica)

Parametri opzionali: · operation – Tipo di messaggio che si intende spedire.

I possibili valori sono:

- TEXT - messaggio di testo – default- WAPPUSH - messaggio WapPush- UCS2 – messaggio con codifica UCS2- MULTITEXT – messaggio concatenato

I messaggi UCS2 e MULTITEXT possono essere inviati solamente in qualità Notifica. Attraverso l'opzione MULTITEXT sarà possibile inviare un testo lungo fino a 804 caratteri, che verrà automaticamente suddiviso ed inviato dal sistema come più SMS i quali verranno ricevuti dal cellulare come un unico testo.

· url – Indirizzo URL al quale si dovrà collegare il cellulare che riceve ilmessaggio WAPPUSH.

· return_id – Se impostato uguale a 1 verrà restituito l’identificativo dellaspedizione da utilizzare nel casosi richieda lo stato della spedizione tramite post/get http (es.HTTP00000000111).

Il server risponderà con “OK <costo>”, ove <costo> è il credito scalato per l'invio del messaggio.

In caso di errore la risposta del server sarà “KO <testo_errore>”.

Codici errore:

· KO Accesso non consentito (Utente non abilitato).· KO Accesso non consentito (IP non abilitato).· KO Parametro <nome parametro> non impostato.· KO Il parametro <nome parametro> può contenere al massimo <n> numeri.· KO Parametro <nome parametro> non valido.· KO Operatore sconosciuto.· KO Credito insufficiente.· KO Impossibile accodare il/i messaggio/i.

Esempi di invio sms TEXT – MULTITEXT - UCS2:

Un sms può essere inviato semplicemente copiando i link riportati di seguito ed incollandoli nella barra degli indirizzi di un browser dopo aver sostituito username, password e numero di telefono del destinatario con valori corretti:

Messaggio TEXT (160 caratteri)

http://login.ciaosms.it/sms/send.php?user=username&pass=password&rcpt=%2b3934 81234567&data=messaggiodiprova&sender=sms&qty=a

Messaggio MULTITEXT (sms oltre i 160 caratteri messaggio concatenato)

http://login.ciaosms.it/sms/send.php?user=username&pass=password&operation=MU

LTITEXT&rcpt=%2b393481234567&sender=sms&qty=n&data=messaggi odiprovalungopiudi160caratteri...ecc...ecc

Messaggio UCS2 (messaggio con codifica UCS2 - sms con caratteri speciali)

http://login.ciaosms.it/sms/send.php?user=username&pass=password&operation=UC S2&rcpt=%2b393487633474&sender=sms&qty=n&data= %CE%B1%CE%B2%CE%B3

(in questo esempio è stato simulato l’invio di un sms con caratteri speciali dell’ alfabeto greco. Il cellulare riceverà i caratteri greci alfa, beta, gamma)

3 - Invio multiplo SMS tramite richiesta POST/GET HTTP

URL: http://login.ciaosms.it/sms/batch.php Parametri

autenticazione:

· user – Login cliente· pass – Password cliente

Parametri obbligatori:

· rcpt – Elenco numeri nel formato internazionale %2bXXYYYZZZZZZ,separati da virgola

· data – Testo del messaggio (max 160 caratteri)

· sender – Mittente del messaggio (max 11 caratteri alfanumerici o numero%2bXXYYYZZZZZZZ)

· qty – Qualità del messaggio: (ll, a, n – bassa, automatica, notifica)

Parametri opzionali:

· operation – Tipo di messaggio che si intende spedire.

I possibili valori sono:

- TEXT - messaggio di testo – default- WAPPUSH - messaggio WapPush- UCS2 – messaggio con codifica UCS2- MULTITEXT – messaggio concatenato

I messaggi UCS2 e MULTITEXT possono essere inviati solamente in qualità Notifica. Attraverso l'opzione MULTITEXT sarà possibile inviare un testo lungo fino a 804 caratteri, che verrà automaticamente suddiviso ed inviato dal sistema come più SMS i quali verranno ricevuti dal cellulare come un unico testo.

· Ignore Err=true – per scartare dalla lista i numeri troppo corti o troppolunghi, senza mandare in errore tutta la spedizione multipla.

Esempi:

quando si invia aggiungere il parametro "ignoreErr=true" (booleano), il sistema non blocca la spedizione ma invia il messaggio a tutti i numeri corretti.

Es:

http://login.ciaosms.it/sms/batch.php?user=username&pass=password&operation=TEXT&rcpt=%2b393 33000000,%2b39123&sender=mittente&data=testo&qty=a&ignoreErr=true

Invia l'SMS al numero +39333000000 e restituisce errore per il numero +39123

http://login.ciaosms.it/sms/batch.php?user=username&pass=password&operation=TEXT&rcpt=%2b393 33000000,%2b39123&sender=mittente&data=testo&qty=a

Senza il parametro "ignoreErr=true" nessun messaggio parte.

· url – Indirizzo URL al quale si dovrà collegare il cellulare che riceve ilmessaggio WAPPUSH.

· return_id – Se impostato uguale a 1 verrà restituito l’identificativo dellaspedizione da utilizzare nel casosi richieda lo stato della spedizione tramite post/get http (es.HTTP00000000111).·Il server risponderà con “OK”. In caso di errore la risposta del server sarà“KO <testo_errore>”.

4 - Controllo Credito SMS rimanente tramite richiesta POST/GET HTTP

URL: http://login.ciaosms.it/sms/credit.php

Parametri autenticazione:

· user – Login cliente· pass – Password cliente

Parametri opzionali:

· type – Tipo di controllo (“credit” credito residuo – default -, “ll” messaggibassa qualità, “a” messaggi alta qualità)

Il server risponderà con “OK <VALORE>” ove <VALORE> è il numero di sms o il credito residuo in euro , a seconda del parametro type specificato. In casodi errore la risposta del server sarà “KO <testo_errore>”.

Codici errore: · KO Accesso non consentito (Utente non abilitato).· KO Accesso non consentito (IP non abilitato).· KO Parametro type non corretto· KO Errore Interno.· KO Accesso non consentito· KO Parametri non corretti

Esempio:

http://login.ciaosms.it/sms/credit.php?user=username&pass=password&type=a

5 - Controllo stato Notifica tramite richiesta POST/GET HTTP

Url: http://login.ciaosms.it/sms/batch-status.php

Parametri autenticazione:

· user – Login cliente· pass – Password cliente

Parametri obbligatori:

· id – Identificativo della spedizione (request_id specificato al momento dell’invio della richiesta)

· type – Tipo di report desiderato (“notify” stato delle notifiche dei messaggiinviati)

(“queue” stato accodamento sms)

· schema – Schema del report ( “1” solo codice errore) ( “2” codice di errore specifico)

Il server risponderà con i dati del report richiesto on formato CVS con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In caso di errore la risposta del server sarà “KO <testo_errore>”.

Codici errore:

· KO Accesso non consentito (Utente non abilitato).· KO Accesso non consentito (IP non abilitato).· KO Parametro <nome parametro> non impostato.· KO Il parametro <nome parametro> non corretto· KO Errore interno· KO Accesso non consentito· KO Parametri non corretti

Esempio:

http://login.ciaosms.it/sms/batch-status.php?user=username&pass=password&id=HTTP……….&type=notify&schema=1

Stati di errore riscontrabili al momento dell'invio utilizzando il "sendStatus.php":

Queue:

100 - Waiting 102 - Temporary failure 200 - Processed 300 - Permanent failure

Notify:

100 - Waiting 200 - Delivered 300 - Not delivered (schema 1) - "Codice di errore specifico" (schema 2)

MNC:

100 - Waiting 200 - Exist 300 – Unknown subscriber

Questa è una breve lista di possibili notifiche d'errore:

KO - Teleservice not provisioned (Numero non abilitato in ricezione): il messaggio non può essere consegnato perchè il numero non supporta la ricezione di sms.

KO - Unknown Subscriber: il numero è inesistente.

KO - Absent Subscriber: numero assente.

KO - Notifica non disponibile: è terminato il tempo di validità per la consegna dei messaggi.

KO - Controlling MSC system failure: l'MSC (Mobile Switching Centre) è un apparato dell'architettura della rete GSM che si occupa dello

smistamento dei messaggi tra operatori mobili. In particolare questo problema dipende dall'MSC dell'operatore destinatario del messaggio. Spesso accade a causa di un sovraccarico dell'MSC.

KO - Customer is barred according to the MT HLR from receiving SMS: il numero è stato bloccato dall'operatore del destinatario.

KO - Equipment protocol error: problema del protocollo dell'operatore del numero del destinatario.

KO - Expired: il tempo disponibile per poter consegnare l'SMS è terminato e non è stato possibile durante questo periodo recapitare l'sms.

KO - MT number is unknown in the MT network's HLR: il numero è disattivato o inesistente. Tradotto letteralmente : il numero risulta sconosciuto all'interno dell'HLR (Home Location Register) della rete del numero destinatario.

KO - Memory capacity exceeded (Memoria SMS esaurita): Significa che il cellulare ha terminato lo spazio per poter ricevere l'SMS.

KO - SS7 error. "No response from peer" : il numero è stato disattivato o è inesistente.

6 - Controllo stato Notifica Multipla per data, tramite richiesta POST/GET HTTP

http://login.ciaosms.it/sms/batch-status-interval.php Parametri

autenticazione:

· user – Login cliente· pass – Password cliente

Parametri obbligatori:

· from – Data ora di inzio dell’intervallo desiderato. La data dovrà essere nelformato “gg/mm/aaaa/hh/mm” (es. per richiedere lo stato degli invii effettuatia partire dalle ore 10.30 del 12/08/2008 si dovrà scrivere “12/08/2008/10/30”).

· to – Data/ora di fine dell’intervallo desiderato. La data dovrà essere nelformato “gg/mm/aaaa/hh/mm

· type Tipo di report desiderato (“queue” stato accodamento messaggi,“notify” stato delle notifiche dei messaggi inviati, “mnc” stato delle richiesteMNC)

· schema – Schema del report (i formati sono 1 e 2 come nel caso di batch-status.php).

Il server risponderà con i dati del report richiesto in formato CSV con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In ogni riga verrà specificato l’identificativo della spedizione cui appartiene l’elemento. Questo identificativo corrisponde a quello restituito dal sistema al momento dell’invio se si è impostato il parametro return_id a 1.

In caso di errore la risposta del server sarà “KO <testo_errore>”.

Esempio report notify:

id,dest,status,status_text,id_spedizione

9184,+393331111111,100,Delivered, HTTP00000000111 9185, +393331111111,Unknown subscriber, HTTP00000000111

Esempio di interrogazione:

http://login.ciaosms.it/sms/batch-status-interval.php?user=xxxxxxx &pass=zzzzzzzzz&from=10/12/2008/10/00&to=20/01/2009/08/00&type=notify &schema=1

Per il momento non ci sono limitazioni riguardo la dimensione dell'intervallo temporale .

7 – Ricezione delle notifiche via POST HTTP

Il sistema permette di ricevere le notifiche dei messaggi inviati mediante un POST HTTP.

7.0.1 Fase di invio degli SMS

Per poter abilitare la funzionalità di richiesta delle notifiche mediante POST HTTP è necessario, in fase di invio, settare il parametro qty=n e validare il parametro batch_code, settandolo con un valore a discrezione del cliente. Il parametro batch_code verrà restituito al cliente nella notifica stessa e potrà eventualmente essere utilizzato per abbinare la "mobile delivery notification" con il relativo invio.

L'URL a cui il sistema posterà le notifiche lo si può settare in 2 modi:

1.direttamente dal pannello ciaosms.it alla voce "Impostazioni > Impostazionimessaggi > URL notifiche" Questo valore verrà utilizzato come URL di default.

2. Passandolo direttamente alle api mediante il parametro notify_url

Il metodo con cui il sistema seleziona l'URL a cui postare le notifiche è riassunto nella seguente tabella:

URL nel parametro notify_url URL settato su pannello URL a cui verrà postata la notifica

non settato non settato La notifica non viene postata

non settato http://miosito/notifiche-pannello.dfl http://miosito/notifiche-pannello.dfl

http://miosito/notifiche-api.api non settato http://miosito/notifiche-api.api

http://miosito/notifiche-api.api http://miosito/notifiche-pannello.dfl http://miosito/notifiche-api.api

7.0.2 Messaggi concatenati

Con il pannello CiaoSMS.it è possibile inviare attraverso un unico POST/GET HTTP un SMS con testo piu lungo di 160 caratteri utilizzando l'operation MULTITEXT. Con questa funzionalità è possibile spedire un testo lungo fino a 918 caratteri che verrà automaticamente suddiviso ed inviato dal sistema come più SMS. In questo caso l'operatore telefonico inoltra al sistema una notifica per ogni SMS parte dell'intero messaggio.

Per riconoscere a quale parte dell'SMS è relativa la notifica ricevuta, si può utilizzare l'udh, valore che verrà postato come parametro della notifica. Maggiori informazioni sul parametro udh sono disponibili nel paragrafo successivo.

7.1 – Specifiche per la ricezione dei POST HTTP

Di seguito sono riportati i parametri che verranno inviati mediante POST HTTP. I parametri sono :

- rcpt

- status

- time

- date

- udh

- act

- return_id

rcpt �conterrà il numero di telefono.

status �conterrà lo stato del messaggio.

In caso di messaggio correttamente consegnato la notifica sarà del tipo "Delivered (Consegnato)".

In caso d'errore verrà restituita una notifica d'errore generica o con una breve descrizione dell'errore, a discrezione degli operatori telefonici.

�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, verrà restituita l'ora di ricezione della notifica d'errore.

�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, verrà restituita la data di ricezione della notifica d'errore.

udh �il valore di questo parametro è espresso come numero esadecimale nel seguente modo:

udh = aabbcc

dove aa : id del messaggio

dove bb : numero totale delle parti del messaggio

dove cc : parte del messaggio �

act �conterrà il batch_code impostato dal cliente al momento dell'invio.

�return_id �conterrà l’identificativo della spedizione, generato dal sistema, da utilizzare nel caso si richieda lo stato della spedizione tramite batch-status (vedi relativo capitolo alla fase di spedizione)

Esempio :

http://login.ciaosms.it/sms/send.php?user=username&pass=password&rcpt=%2b393481234567&data= messaggiodiprova&sender=sms&qty=n&batch_code=1234&notify_url=http://www.sito.url/script

In questo modo, quando il sistema riceverà la DLR la posterà all'URL "http://www.sito.url/script".

Questo è un esempio di parametri che si riceverà in POST per il precedente messaggio:

[status] => Delivered (Consegnato) [time] => 16:45:06 [date] => 2012-06-28 [act] => 1234 [udh] => [return_id] => 36377013 [rcpt] => +393481234567

8 - Invio multiplo richieste MNC tramite richiesta POST/GET http

URL: http://login.ciaosms.it/sms/mnc.php

Parametri autenticazione:

user – Login cliente

pass – Password cliente

Parametri obbligatori:

− numbers – Elenco numeri nel formato internazionale +XXYYYZZZZZZ,separati da virgola.

Parametri opzionali:

− return_id – Se impostato uguale a 1 verrà restituito l’identificativo dellaspedizione da utilizzare nel caso si richieda lo stato della spedizione tramitepost/get http (es. HTTP00000000111).

Il server risponderà con “OK”. In caso di errore la risposta del server sarà “KO <testo_errore>”.

Codici errore:

KO Accesso non consentito (Utente non abilitato).

KO Accesso non consentito (IP non abilitato).

KO Parametro <nome parametro> non impostato.

KO Il parametro <nome parametro> può contenere al massimo <n> numeri.

KO Parametro <nome parametro> non valido.

KO Impossibile accodare le richieste.

KO Accesso non consentito.

KO Parametri non corretti.

ESEMPIO DI RICHIESTA:

• http://login.ciaosms.it/sms/mnc.php?user=username&pass=password&numbers=%2B3934 81234567,%2b393331234567&return_id=1

8.1 - Controllo stato MNC tramite richiesta POST/GET

http Url: http://login.ciaosms.it/sms/batch-status.php

Parametri autenticazione:

· user – Login cliente

· pass – Password cliente

Parametri obbligatori:

· id – Identificativo della spedizione (request_id specificato al momento dell’invio della richiesta)

· type – Tipo di report desiderato

(“notify” stato delle notifiche dei messaggi inviati)

(“queue” stato accodamento sms)

(“mnc” stato mnc)

· schema – Schema del report

( “1” solo codice errore)

( “2” codice di errore specifico)

Il server risponderà con i dati del report richiesto on formato CVS con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In caso di errore la risposta del server sarà “KO <testo_errore>”.

Codici errore:

· KO Accesso non consentito (Utente non abilitato).

· KO Accesso non consentito (IP non abilitato).

· KO Parametro <nome parametro> non impostato.

· KO Il parametro <nome parametro> non corretto

· KO Errore interno

· KO Accesso non consentito

· KO Parametri non corretti

Esempio:

http://login.ciaosms.it/sms/batch- status.php?user=username&pass=password&id=HTTP..........&type=mnc&schema=1

CiaoSMS by Bitway Italia – Via Tommaso Fiore 1/K – 70015 Noci ( Bari ) – tel.080 222 12 16