Invio di un sms ad uno o più destinatari singoli o verso uno o più gruppi della rubrica.
È possibile testare l'invio valorizzando il parametro sandbox
a true nella richiesta.
Il parametro statusCallback
consente di registrare un URL al quale sarà inviata via HTTP una notifica con lo stato(Consegnato,Non Consegnato) del Sms.
Per maggiori informazioni fare riferimento alla tabella parametri sottostante.
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
authKey | Si | String |
authKey associata al tuo profilo su SmsHosting.it. Visita la sezione gestione sicurezza API nella tua area privata per recuperare tale valori |
authSecret | Si | String |
authSecret associata al tuo profilo su SmsHosting.it. Visita la sezione gestione sicurezza API nella tua area privata per recuperare tale valori |
from | No | String |
Il mittente del Sms. Può essere un numero di telefono validato oppure una stringa alfanumerica di 11 caratteri. Se non specificato viene usato il mittente di default del proprio profilo. |
to |
No (Obbligatorio valorizzare almeno uno tra il campo to e group) |
String |
Il destinatario del messaggio. Deve essere un numero di cellulare compreso di prefisso internazionale. Ad esempio: 393481234567 oppure 393481234567,393481234568,393481234568 Alternativamente il parametro può essere valorizzato con un array JSON contenente gli oggetti che descrivono il destinatario. Ad esempio: [{msisdn:'393481234567'},{msisdn:'393481234568'},{msisdn:'393481234568'}] |
group |
No (Obbligatorio valorizzare almeno uno tra il campo to e group) |
String |
Id del gruppo in Rubrica al quale inviare È possibile specificare più gruppi della rubrica separandoli con il carattere virgola ",". Ad esempio se nellla rubrica sono presenti i gruppi Amici(id=1) e Scuola(id=2) sarà possibile indicare: 1 oppure 1,2 |
text | Si | String |
Testo del messaggio. Se il messaggio supera i 160 caratteri vengono inviati più sms concatenati fino ad una massimo di 7. Il testo può contenere dei placeholder che saranno sostituiti in fase di invio dai valori associati al rispettivo destinatario. Il placeholder va specificato con la sintassi ${nome proprietà} Nel caso il testo contenga dei placeholder il campo to deve essere valorizzato con un array JSON ed ogni oggetto dell'array deve contenere la proprietà indicata nel placeholder. Ad esempio: to=[{msisdn:'393481234567',nome:'Mario Rossi'},{msisdn:'393481234568',nome:'Luigi Bianchi'}] text=Invio sms di test a ${nome} |
date | No | String |
Sms differito Data (in formato yyyy-MM-dd'T'HH:mm:ssZ) alla quale sarà inviato il messaggio.Se non viene specificato alcun valore il messaggio viene inviato immediatamente. Ad esempio: 2014-12-25'T'08:00:00+0200 indica il 25/12/2014 alle 08:00:00 riferito al GMT +2 |
transactionId | No | String |
Un identificatore personale dell'invio. Consente di assegnare a tutti gli sms inviati con una chiamata lo stesso identificatore in modo da utilizzare questo parametro per ricevere lo stato dei messaggi. massimo 60 caratteri |
sandbox | No | Boolean |
Consente di testare la chiamata senza inviare effettivamente il messaggio. Parametro utile in fase di sviluppo di eventuali integrazioni con le REST API. Possibili valori true/false |
statusCallback | No | String | URL al quale sarà inviata via HTTP una notifica con lo stato(Consegnato,Non Consegnato) del Sms |
encoding | No | String |
L'encoding da utilizzare per il testo del messaggio. I possibili valori sono: 7BIT - Encoding standard per i messaggi GSM. La lunghezza massima per un singolo sms è di 160 caratteri. UCS2 - Encoding a 8-bit per inviare messaggi GSM con contenuto non ASCII. La lunghezza massima per un singolo sms è di 70 caratteri. AUTO - L'encoding da utilizzare viene automaticamente identificato in base al contenuto del campo testo. Default : 7BIT |
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 |
Parametri non validi I possibili
BAD_TEXT_PLACEHOLDER - text contiene dei placeholder non sostituibili
|
405 | Metodo HTTP non consentito |
500 | Errore generico |
Dati Invio
Proprietà | Descrizione |
---|---|
from | Il mittente del messaggio. |
text | Testo Sms |
transactionId |
identificatore dell'invio Se non specificato in fase di richiesta verrà generato un transactionId automaticamente dalle REST API |
smsInserted | Numero Sms inseriti |
smsNotInserted | Numero Sms Non inseriti |
sms |
Lista degli Sms. Ogni sms è descritto dalla proprietà: to - numero di cellulare al quale è stato inviato il messaggio id - id interno del messaggio.Valore utile per richiedere lo stato del messaggio con la funzione di Cerca Sms status - Stato del messaggio. Viene valorizzato ad statusDetail - nel caso il messaggio non venga inserito (status = |
Esempio:
curl 'https://api.smshosting.it/rest/api/smart/sms/send?authKey=[AUTH_KEY]&authSecret=[AUTH_SECRET]&text=sms+di+test+con+simbolo+%E2%82%AC&to=393470000&from=mrossi'
{ "from":"mionegozio", "text":"sms di test con simbolo€", "transactionId":"c8e814b97a5dcebfc67840201456e978", "smsInserted":2, "smsNotInserted":0, "sms":[ { "id":296841, "to":"393478133825", "status":"INSERTED" }, { "id":296842, "to":"393495059253", "status":"INSERTED" } ] }
Ricerca degli sms inviati.
Parametro | Obbligatorio | Tipo | Descrizione |
---|---|---|---|
authKey | Si | String |
authKey associata al tuo profilo su SmsHosting.it. Visita la sezione gestione sicurezza API nella tua area privata per recuperare tale valori |
authSecret | Si | String |
authSecret associata al tuo profilo su SmsHosting.it. Visita la sezione gestione sicurezza API nella tua area privata per recuperare tale valori |
id | No * | String |
Id interno del messaggio inviato È possibile specificare più id separandoli con il carattere virgola ",". Ad esempio: 12312 oppure 432432,543543,435435 |
transactionId |
No * |
String | TransactionId assegnato all'invio |
msisdn |
No * |
String | Numero al quale è stato inviato il messaggio |
fromDate | No * | String | Data dalla quale gli sms sono stati inviati in formato yyyy-MM-dd'T'HH:mm:ssZ |
toDate | No | String | Data fino alla quale gli sms sono stati inviati in formato yyyy-MM-dd'T'HH:mm:ssZ |
status | No * | String | Stato degli sms |
offset | No | Integer |
Posizione del primo risultato che verrà restituito. Esempio: Se la ricerca trova 100 sms, il campo offset viene valorizzato a 50 ed il campo limit a 10 verranno restituiti gli sms da 51 a 60. Default : 0 |
limit | No | Integer |
Numero di risultati che verranno restituiti. Default : 20 |
* È richiesto che almeno un parametro sia valorizzato
HTTP Status Code
Codice | Descrizione |
---|---|
200 | ok |
400 |
Parametri non validi I possibili
|
405 | Metodo HTTP non consentito |
500 | Errore generico |
La chiamata ritorna una lista di sms inviati.
Proprietà | Descrizione |
---|---|
smsList |
Lista degli sms ricevuti Ogni sms è descritto dalle proprietà: id - id interno messaggio to - destinatario del messaggio text - testo del messaggio from - mittente del messaggio status - stato del messaggio.Vedi la tabella sottostante. insertDate - data inserimento del messaggio nel formato yyyy-MM-dd'T'HH:mm:ssZ sentDate - data invio del messaggio nel formato yyyy-MM-dd'T'HH:mm:ssZ deliveryDate - data consegna del messaggio nel formato yyyy-MM-dd'T'HH:mm:ssZ transactionId - Identificatore dell'invio price - costo del messaggio |
metadata |
Metadata utili per la paginazioni Per maggiori dettagli sul funzionamento della paginazione visita la pagina dedicata |
I possibili stati di un sms(campo status) sono
Codice | Descrizione |
---|---|
PENDING | Sms in coda per l'invio |
SENT | Sms inviato all'operartore |
NOSENT | Sms non inviato all'operartore |
DELIVERED | Sms consegnato al cellulare del destinatario |
NOTDELIVERED | Sms non consegnato al cellulare |
Esempio:
curl 'https://api.smshosting.it/rest/api/smart/sms/search?authKey=[AUTH_KEY]&authSecret=[AUTH_SECRET]&transactionId=111'
{ "metadata":{ "count":1, "offset":0, "limit":20 }, "smsList":[ { "id":389395385, "to":"393480000000", "text":"Test Sms", "from":"mrossi", "status":"DELIVERED", "insertDate":"2014-01-13T15:01:35+0100", "sentDate":"2014-01-13T15:01:37+0100", "deliveryDate":"2014-01-13T15:01:40+0100", "transactionId":"72810108d4114097b9edb42b255b273c", "price":0.0945 } ] }