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 con identità validata tramite SPID o documento d'identità e di aver in uso su questo account almeno un numero VoIP di rete fissa Messagenet 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 massimo di SMS processabili al secondo: 10 invii.
- Numero di singoli SMS addebitati: Numero di destinatari * ((Lms + 159) DIV 160) dove DIV è l’operatore di divisione fra interi.
Esempio: 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
[&format=json|plist|xml]
Autenticazione: i parametri <auth_userid>
e <auth_password>
specificano le credenziali di accesso ai servizi Messagenet.
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>
specifica il mittente del messaggio; i valori ammessi sono i numeri Messagenet attribuiti al medesimo utente, nel formato internazionale e164 senza leading plus ("+") (ovvero390212345678
per il numero fisso italiano 0212345678) oppure un eventuale mittente testuale qualora preventivamente abilitato per lo specifico utente; il parametro è obbligatorio e se omesso, od errato, causerà rigetto dell'invio;
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 (ovvero il Codice Utente) con il quale è stato effettuato l'invio del messaggio.
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&sender=390212345678&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&sender=390212345678&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&sender=390212345678&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.
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 (ovvero il Codice Utente) con il quale è stato effettuato l'invio del messaggio.
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 $sender = '390212345678' 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, sender => $sender, 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&sender=390212345678&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