Invio automatico SMS coi software aziendali - API per sviluppatori

Documentazione API SMS per sviluppatori

 

Introduzione

Comunicazioni circolari a testo fisso o personalizzato, campagne pubblicitarie mirate, fidelizzazione della clientela, doppia validazione degli utenti del proprio sito web, attivazione di app smartphone o semplici promemoria sono alcuni degli utilizzi più comuni dell'invio di SMS automatici dai propri programmi software.

Gli sviluppatori web, desktop, cloud o app smartphone possono utilizzare in modo semplice e immediato l’infrastruttura Messagenet dalla propria applicazione per spedire SMS ad uno o più destinatari e di ottenere da programma lo stato di consegna per ogni singolo SMS inviato, aggiungendo certezza alla propria soluzione.

Prerequisiti, Attivazione e Prezzi

Nessun costo fisso di attivazione o canone: si paga solo in base al numero di SMS inviati. E’ necessario essere utenti registrati del sito messagenet.com e aver convalidato almeno un numero di cellulare da indicare come mittente. Il costo di ogni singolo SMS inviato è scalato dal credito: basta acquistare una ricarica di importo sufficiente per i propri scopi. Per i prezzi di invio di un singolo SMS ad un singolo destinatario e per le destinazioni/operatori raggiungibili, consultare la pagina delle tariffe SMS. Il costo è indipendente dal paese/operatore di destinazione.

Background

Messagenet offre dal 2005 il servizio SmartSMS per l'invio di singoli SMS tramite una semplice interfaccia web. Il sistema consente anche di conoscere in tempo reale lo stato di consegna di ogni SMS spedito.

Contatti

Per ulteriori informazione, scrivere a support@messagenet.it

 

Specifiche

Set di caratteri supportati per il testo: GSM 7 bit encoding con l’estensione per parentesi quadre e graffe, pipe e simbolo dell’euro. L’utilizzo all’interno del testo di caratteri al di fuori del set porta a risultati non prevedibili.
Lunghezza massima di ogni singolo SMS (Lsms): 160
Lunghezza del testo (Ltx):  > 0
Lunghezza del messaggio spedito (Lms): solitamente Lms=Ltx, ma in alcuni casi Lms>Ltx, ad esempio un testo di 160 caratteri che contiene il simbolo dell’euro porta ad una lunghezza totale del messaggio ai fini SMS di 161 caratteri che viene viene spedito con due singoli SMS per ogni destinatario. Questo comportamento non è differente da quanto succede inviando lo stesso SMS dal cellulare.
Numero di singoli SMS addebitati: Numero di destinatari * ((Lms + 159) DIV 160) dove DIV è l’operatore di divisione fra interi.
Esempi: 5 destinatari, lunghezza del testo 100 caratteri = 5 SMS singoli. 5 destinatari, testo contiene una volta il simbolo dell’euro, lunghezza del testo 160 caratteri = lunghezza messaggio 161; 10 SMS singoli. 5 destinatari, lunghezza del testo 200 caratteri = 10 SMS singoli.

 

IMPORTANTE: non pubblicare mai su siti web o dentro a email o su strumenti similari le chiamate personalizzate alle API in quanto contengono le vostre credenziali.

Invio SMS

URL: https://api.messagenet.com/
POST /api/send_sms HTTP/1.1
auth_userid=XXX&auth_password=XXX
&destination=XXX&text=XXX
[&sender=XXX&report=0|1]
[&format=json|plist|xml]

Autenticazione: i parametri <auth_userid> e <auth_password> specificano le credenziali di accesso ai servizi Messagenet. Da questa versione è possibile usare anche le credenziali di una URI utente, oltre alle credenziali di accesso al sito.

Destinazioni: il parametro <destination> permette di specificare una o piu' destinazioni per il messaggio; destinazioni multiple vanno separate con un punto e virgola (;). Nel caso il prefisso internazionale sia omesso, viene assunto per default +39.

Testo del messaggio: il parametro <text> contiene il testo del messaggio da inviare

Sender: il parametro <sender> consente di specificare il mittente del messaggio; valori ammessi sono 'web' (per messaggi la cui risposta viene visualizzata tramite Web) oppure un numero mobile precedentemente convalidato sul sito Messagenet. Il parametro e' opzionale (default = 'web'). Nel caso sia inserito un numero non validato, il parametro viene modificato in 'web' e nella risposta viene inserito il warning “Sender not validated”

Report: il parametro <report> specifica se nell'area utente sarà presente il rapporto di consegna del messaggio. In caso il valore sia 0, l'API check_sms potrebbe non fornire dati accurati.

Formato: il parametro <format> specifica il formato della risposta.

Risposte

La risposta contiene le seguenti informazioni:

http_status: fornisce informazioni sullo stato dell'operazione e sulle possibili cause di fallimento:

200 OK
401 Not authorized
402 No credit
405 Request error (use POST)
500 No text | Number error| Other

timestamp: data e ora di invio
status:codice errore e descrizione errore/risultato operazione
userid: lo userid con il quale è stato effettuato l'invio del messaggio. Nota: in questo campo il valore indicato sarà sempre quello di accesso al sito, anche se nella chiamata è stata specificata come autenticazione la URI dell'utente. Ad esempio, eseguendo una chiamata con la URI 1234567 appartenente all'utente 67890, il valore di questo campo sarà 67890.
sent: lista dei numeri verso cui il messaggio e' stato inviato con successo; per ogni numero viene riportato un identificatore (message_id) che consente di determinare lo stato di effettiva consegna del messaggio
failed: lista dei numeri la spedizione verso i quali e' fallita, con indicazione di codice di errore e descrizione del motivo del fallimento
warning: riporta eventuali warning:
            Sender not validated

Codici errore/Warning

0 OK
403 Not authorized
101 Credit error
102 No text
103 Number error
104 Sender not validated error
105 Request error (use HTTPS/POST)
106 All sending attempts failed
107 Auto error
199 Generic error
200 Sender not validated warning

La risposta è formattata a seconda del parametro format. Di seguito degli esempi a fronte della chiamata corrispondente.

format = json (content type: application/json)

https://api.messagenet.com/api/send_sms/?auth_userid=1234567&auth_password=password&destination=399991234567&text=test&format=json
  {
http_status : {
value : 200
},
timestamp : {
value : "2010-07-1210:26:00"
},
status : {
code : 0
},
message_status : {
value : 0,
description : "Delivered to Messagenet gateway"
}
}

format = plist (content type: text/x-plist)

  https://api.messagenet.com/api/send_sms/?auth_userid=1234567&auth_password=password&destination=399991234567&text=test&format=plist
<plist version="1.0">
<dict>
<key>http_status</key>
<dict>
<key>value</key>
<string>200</string>
</dict>
<key>sent</key>
<array>
<dict>
<key>message_id</key>
<string>1569546</string>
<key>value</key>
<string>+399991234567</string>
</dict>
</array>
<key>status</key>
<dict>
<key>code</key>
<string>0</string>
<key>description</key>
<string>OK</string>
</dict>
<key>timestamp</key>
<dict>
<key>value</key>
<string>2013-03-05T15:07:53</string>
</dict>
<key>userid</key>
<string>1234567</string>
</dict>
</plist>

format = xml (content type: text/xml)

https://api.messagenet.com/api/send_sms/?auth_userid=1234567&auth_password=password&destination=399991234567&text=test&format=xml
<results>
<http_status>
<value>200</value>
</http_status>
<sent>
<message_id>1569557</message_id>
<value>+399991234567</value>
</sent>
<status>
<code>0</code>
<description>OK</description>
</status>
<timestamp>
<value>2013-03-05T15:14:58</value>
</timestamp>
<userid>1234567</userid>
</results>

Controllo stato SMS spediti

URL: https://api.messagenet.com/
POST /api/check_sms HTTP/1.1
auth_userid=XXX&auth_password=XXX
&message_id=YYYYYY
[&destination=XXX]
[&text=XXX]
[&format=json|plist|xml]

Autenticazione: i parametri <auth_userid> e <auth_password> specificano le credenziali di accesso ai servizi Messagenet. Da questa versione è possibile usare anche le credenziali di una URI utente, oltre alle credenziali di accesso al sito.
Identificativo: il parametro <message_id> indica di quale messaggio ottenere lo stato.
Formato: il parametro <format> specifica il formato della risposta.

Risposte

La risposta contiene le seguenti informazioni:
http_status: fornisce informazioni sullo stato dell'operazione e sulle possibili cause di fallimento:

200: OK
401: Not authorized
405: Request error (use POST)
500: Wrong message_id| Other

status:codice errore e descrizione errore/risultato operazione
message_status: codice di stato e descrizione stato consegna del messaggio

0 Delivered to Messagenet gateway
1 Delivered to network
2 Receipt received
3 Cancelled

userid: lo userid con il quale è stato effettuato l'invio del messaggio. Nota: in questo campo il valore indicato sarà sempre quello di accesso al sito, anche se nella chiamata è stata specificata come autenticazione la URI dell'utente. Ad esempio, eseguendo una chiamata con la URI 1234567 appartenente all'utente 67890, il valore di questo campo sarà 67890.
timestamp: data e ora di consegna dell'SMS

Codici errore/Warning

0 OK
100 Not authorized
105 Request error (use HTTPS/POST)
108 Wrong message_id
199 Generic error

La risposta è formattata a seconda del parametro format.

format = json (content type: application/json)

https://api.messagenet.com/api/check_sms/?auth_userid=1234567&auth_password=password&message_id=1569557&format=json {
http_status : {
value : 200
}
,
timestamp : {
value : "2010-07-1210:26:00"
}
,
status : {
code : 0
}
,
message_status : {
value : 0,
description : "Delivered to Messagenet gateway"
}
}

format = plist (content type: text/x-plist)

https://api.messagenet.com/api/check_sms/?auth_userid=1234567&auth_password=password&message_id=1569557&format=plist
<plist version="1.0">
<dict>
<key>http_status</key>
<dict>
<key>value</key>
<string>200</string>
</dict>
<key>id</key>
<string>1569557</string>
<key>message_status</key>
<dict>
<key>code</key>
<string>2</string>
<key>description</key>
<string>Receipt received</string>
</dict>
<key>status</key>
<dict>
<key>code</key>
<string>0</string>
<key>description</key>
<string>OK</string>
</dict>
<key>timestamp</key>
<dict>
<key>value</key>
<string>2013-03-05T15:14:59</string>
</dict>
<key>userid</key>
<string>1234567</string>
</dict>
</plist>

format = xml (content type: text/xml)

https://api.messagenet.com/api/check_sms/?auth_userid=1234567&auth_password=password&message_id=1569557&format=xml
<results>
<id>1569557</id>
<http_status>
<value>200</value>
</http_status>
<message_status>
<code>2</code>
<description>Receipt received</description>
</message_status>
<status>
<code>0</code>
<description>OK</description>
</status>
<timestamp>
<value>2013-03-05T15:14:59</value>
</timestamp>
<userid>1234567</userid>
</results>

Esempio

Ecco un esempio in Perl:

#!/usr/bin/perl

use strict;
use utf8;
use LWP::UserAgent;
use HTTP::Request::Common;

my $auth_userid = '1234567';
my $auth_password = 'password';
my $destination = '+399991234567';
my $text = 'test with €';
my $format = 'json';
my $addr = 'https://api.messagenet.com/api/send_sms/';

# SEND SMS
my $ua = LWP::UserAgent->new;
my $res = $ua->request(POST $addr, [ auth_userid => $auth_userid, auth_password => $auth_password, destination => $destination, text => $text, format => $format ]);

#------------

# CHECK SMS STATUS
# $message_id comes from the response to the SEND SMS routine
my $message_id = '1569557';
$addr = 'https://api.messagenet.com/api/check_sms/';

$res = $ua->request(POST $addr, [ auth_userid => $auth_userid, auth_password => $auth_password, message_id => $message_id, format => $format ]);

Ecco invece uno script in VBA Visual Basic for Applications di Microsoft:

Sub InvioSMS()

Dim objXML As Object
Dim strData As String
Dim strResponse As String

strData = "auth_userid=1234567&auth_password=xXxXxXxX&destination=393xxXXXXXXX&text=Prova"
Set objXML = CreateObject("MSXML2.XMLHTTP")

objXML.Open "POST", "https://api.messagenet.com/api/send_sms?" & strData, False
objXML.send
strResponse = objXML.responseText

MsgBox strResponse
End Sub