1. Il Servizio 2. Protocollo SMS-Server 3. Protocollo HTTP Post e Get

Transcript

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
Copyright © 1998-2013 Agile Telecom S.p.A., All Rights Reserved - Author’s email [email protected] - Last update 14/06/2013)– v6.0.1
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
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
PRIMA FASE: LOGIN
APPENA STABILITA LA CONNESSIONE VIA SOCKET CON IL SERVER DI AGILE INVIARE IL PROPRIO LOGIN:
DATA=06h USER 04h PASSWORD 04h
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. 1000 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
SENDER
TEXT
FLASH
FILENAME
destinatario in formato internazionale (es. +393282382832)
nome o numero del mittente (es. “Rossi”)
testo del messaggio (Max. 160 caratteri, es.“Buongiorno a tutti”)
N (messaggio non in formato flash) o F (messaggio in formato flash)
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
1 byte numerico. Specifica la qualità del messaggio
GATEWAY
H=qualità alta (default)
M=qualità media
codice univoco che l’utente deve specificare per la ricezione del delivery report
DELIVERYCODE
(se non specificato non viene richiesto il delivery report) (Alfanumerico, MAX 20 caratteri, es
09012512525405)
è 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/2009 --> DDT20090322150301
+OK xxxxx (dove xxxxxx è il credito residuo dell’account, espresso in millesimi di Euro. 1000 = 1 Euro)
1-a) PER SPEDIRE SMS MULTIPLI CON TESTO E/O MITTENTE DIVERSO (senza richiesta di delivery report):
04h + 04h + 04h
DATA=DATA + 05h + NUMBER + 04h + SENDER + 04h + TEXT + 04h + FLASH + 04h + FILENAME + 04h + GATEWAY +
04h + 04h + 04h + 04h
04h + 04h + 04h + 04h
Page 4/19
1-b) PER SPEDIRE SMS MULTIPLI CON TESTO E/O MITTENTE DIVERSO (con richiesta di delivery report):
04h + 04h + DELIVERYCODE + 04h
04h + 04h + 04h + DELIVERYCODE + 04h
04h + 04h + 04h + DELIVERYCODE + 04h
2-a) PER SPEDIRE SMS MULTIPLI CON LO STESSO TESTO E MITTENTE (senza richiesta di delivery report):
04h + 04h + 04h
DATA=DATA + 07h + NUMBER
DATA=DATA + 07h + NUMBER
2-b) PER SPEDIRE SMS MULTIPLI CON LO STESSO TESTO E MITTENTE (con richiesta di delivery report):
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) )
--------------------------------------------N.B.: PER OGNI DATO INVIATO TRAMITE TCP/IP AGGIUNGERE
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= 70 56
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
‘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(“+39328123465”,”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) \n";
return 0;
}
$str = wrap(pwd());
if($debug) {
print "$str \n";
}
fputs($conn,$str);
if($debug) {
print " After pwd: ".fgets($conn,128)." \n";
}
return $conn;
}
function xDisconnect()
{
global $conn;
fclose($conn);
}
function wrap($data)
Page 6/19
{
$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("+11111111111","+11111111111","+11111111111","+11111111111");
//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/2009 --> DDT20090322150301
$delaydelivery="DDTyyyymmddhhmmss";
//Example: to be delivered in date 2012/12/31 at 23:59:40 you have to set it to: DDT20121231235940
//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 ";
else echo "Sms not sended. $msg ";
}
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
if (strstr($msg,'+Ok')) echo "Sms sent ";
else echo "Sms not sended. $msg ";
}
xDisconnect();
}
else
{
echo "Failed: Could not connect - $errno - $errstr ";
}*/
?>
Page 8/19
3. PROTOCOLLO HTTP POST E GET
Per inviare SMS via post basta spedire una richiesta HTTP POST al seguente indirizzo
http://post.agiletelecom.com/smshurricane3.0.asp
o una richiesta HTTP GET al seguente indirizzo
http://post.agiletelecom.com/smshurricaneGET3.0.asp
Per entrambi I metodi è necessario specificare I valori delle seguenti variabili:
smsTEXT
max 640 char, testo del messaggio (160 caratteri se è un sms singolo; 153 caratteri per ogni sms in
caso di long message)
smsNUMBER
max 16 caratteri, numero telefonico dell’utenza di destinazione in formato internazionale,
+393294938957
E’ possibile mettere fino a 100 numeri di destinazione in formato internazionale separato da “;”
smsSENDER
max 16 cifre per il numero telefonico del mittente in formato internazionale oppure max 11 caratteri per
una stringa di testo alfanumerico
smsGATEWAY
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)
smsTYPE
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
smsUSER
l’user del vostro account
smsPASSWORD
la password del vostro account
smsDELIVERY
campo facoltativo usato per identificare univocamente il messaggio nel caso in cui si voglia richiedere
la notifica di ricezione del messaggio
smsDELAYED
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/2009 --> 20090322150301
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=%2B393381234567&smsSENDER=test&smsTEXT=ciao%20come
%20va&smsGATEWAY=H&smsTYPE=file.sms&smsDELIVERY=20080601_A1
Page 9/19
Risposta da SMSHurricane3.0.asp
******************************************
HTTP/1.1 100 Continue
Server: SMSDriver POST/1.0
Date: mar, 08 apr 2008 11:28:41 GMT
HTTP/1.1 200 OK
Date: mar, 08 apr 2008 11: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 1466298
</body>
</html>
Ecco un esempio di richiesta GET:
GET
/smshurricaneGET3.0.asp?smsUSER=USER&smsPASSWORD=PASSWORD&smsNUMBER=%2B393381234567&smsSENDER=test&smsTEXT=ciao
%20come%20va&smsGATEWAY=H&smsTYPE=file.sms&smsDELIVERY=20080601_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/1.1 100 Continue
Date: ven, 18 apr 2008 17:06:51 GMT
HTTP/1.1 200 OK
Date: ven, 18 apr 2008 17: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 1463212
</body>
</html>
Page 10/19
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 10646 – 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 http://www.unicode.org mentre le tabelle dei
caratteri Unicode si trovano su http://www.unicode.org/charts/
Per inviare un messaggio utilizzando caratteri Unicode bisogna spedire i seguenti dati:
smsNUMBER
numero del destinatario (max 16 cifre, numero telefonico dell’utenza di destinazione in formato
internazionale,+393294938957)
smsSENDER
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)
smsTEXT
esadecimale dei caratteri unicode da spedire (senza spazi tra essi) (max 280 caratteri, 70 visualizzati
sul cellulare)
smsUSER
il proprio user name
smsPASSWORD
la propria password
smsGATEWAY
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)
smsTYPE
file.uni
smsDELIVERY
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:
004300690061006F
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 "+11111111" 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 = "+1111111111"
End If
Page 11/19
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
smpp.agiletelecom.com
Modalità
Transmitter modalità sincrona
Porta
7000
System Id
User name della vostra registrazione
Password
Password della vostra registrazione
TON
1
NPI
1
DCS
0
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. +39338123456 diventa 39338123456)
Per ulteriori informazioni sul metodo SMPP fate riferimento alla documentazione disponibile al link
http://resources.agiletelecom.com/Updates/SMPPv34.pdf
Page 12/19
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 http://www.agiletelecom.com/services/agiletelecomsms.asmx
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
Password
Stringa
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
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
Password
Stringa
Originator
Stringa
messaggio
Destinations
Stringa
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
solo se si neccessita della notifica di ricezione. (*)
Stringa
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
Password
Stringa
Originator
Stringa
messaggio
Destinations
Stringa
Message
Stringa
Testo del messaggio
Gateway
Stringa
Indica il Gateway da usare per inviare il messaggio
DeliveryCode
Stringa
solo se si neccessita della notifica di ricezione.(*)
Page 14/19
Per le funzioni Send_Message, Send_Message_Unicode e Send_Message_on_Gate il server restituisce le seguenti
risposte:
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
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
“http://www.agiletelecom.com/services/AgileTelecomSMS.asmx”.
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
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 = “http://post.agiletelecom.com/smshurricane3.0.asp”
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 +111111111)
Esempio:
POST.Add_Gsm(“+1111111111”)
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", "")
Nessuna risposta
+Ok xxxxx
-Err 101
-Err 102
-Err 103
-Err 104
-Err 105
-Err 106
Significato
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
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
Γ
Λ
Θ
Ξ
Π
Σ
Φ
Ψ
Ω
Δ
Gamma
Ã
Ë
È
ï
Ð
Ó
á
â
Ù
ã
Lambda
Theta
Xi
Pi
Sigma
Phi (Fi)
Psi
Omega
Delta
Valore Ascii Decimale del
carattere da spedire
195
Valore Ascii Esadecimale
del carattere da spedire
0xC3
203
0xCB
200
0xC8
239
0xEF
208
0xD0
211
0xD3
225
0xE1
226
0xE2
217
0xD9
227
0xE3
Page 17/19
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:
http://www.agiletelecom.com/gatecheck/check.aspx
Lo script accetta parametri come QueryString dove:
P = prefisso internazionale
C = nome del carrier che appare nella HOME PAGE www.agiletelecom.com
Ecco alcuni esempi di come poter utilizzare questo servizio:
Per controllare lo stato del servizio verso tutti gli operatori Italiani
http://www.agiletelecom.com/gatecheck/check.aspx?P=+39
Per controllare lo stato del servizio verso Italia TIM
http://www.agiletelecom.com/gatecheck/check.aspx?P=+39&C=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:
http://www.agiletelecom.com/credit.aspx
I parametri da passare alla pagina asp sono i seguenti:
smsUSER = Nome utente del proprio account
smsPASSWORD = Password del proprio account
ad esempio
http://www.agiletelecom.com/credit.aspx?smsUSER=MioUtente&smsPASSWORD=MiaPassword
Si riceverà una risposta del tipo
Nessuna risposta
+Ok xxxxx
-Err 001
Significato
Page 18/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 www.agiletelecom.com
Page 19/19

1. Il Servizio 2. Protocollo SMS-Server 3. Protocollo HTTP Post e Get

Transcript

Documenti analoghi

Tutorial SMS per Cubateamo

SMS SEND: veloce, economico, semplice

Il tradimento ai tempi dell`sms. Segreti e app per non

motorola v3i

Clicca QUI per le API di configurazione

SMS inopportuni

Corriere della Sera Sette Tradimenti digitali

Visualizza articolo

UGITECH il vostro partner per le molle