Invio e dettagli sms

> Invio SMS
> Cerca SMS

Invio SMS

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.

URI

GET https://api.smshosting.it/rest/api/smart/sms/send

Richiesta

ParametroObbligatorioTipoDescrizione
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.
È possibile specificare più numeri di telefono separandoli con il carattere virgola ",".

Ad esempio:

393481234567 oppure 393481234567,393481234568,393481234568

Alternativamente il parametro può essere valorizzato con un array JSON contenente gli oggetti che descrivono il destinatario.
Ogni oggetto deve avere obbligatoriamente la propriertà msisdn valorizzata.
Le altre proprietà di tali oggetti posso essere utilizzate per parametrizzare il testo del messaggio.(vedi il campo text)

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

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_CREDENTIAL - credenziali non valide

BAD_TRANSACTIONID - parametro transactionId non valido

BAD_DATE - formato data differito non valida

BAD_TEXT - parametro text non valido

BAD_TEXT_PLACEHOLDER -  text contiene dei placeholder non sostituibili

BAD_CALLBACK - parametro statusCallback non valido

BAD_ENCODING - parametro encoding non valido

BAD_FROM - parametro from non valido

BAD_GROUP - parametro group non valido

BAD_CREDIT - credito insufficiente per effetturare l'invio

NO_VALID_RECIPIENT - nessun valido destinatario

GENERIC_ERROR - errore interno al server
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 INSERTED nel caso il messaggio sia inserito correttamente, a NOT_INSERTED in caso contrario.

statusDetail - nel caso il messaggio non venga inserito (status = NOT_INSERTED) questo campo riporta un messaggio esplicativo dell'errore avvenuto.
I possibili valori sono :
BADNUMBERFORMAT - Numero del destinatario non corretto
DUPLICATESMS - Sms già inserito nelle ultime 24 ore con identico destinatario, mittente e testo.

 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"
      }
   ]
}

Cerca SMS

Ricerca degli sms inviati.

URI

GET https://api.smshosting.it/rest/api/smart/sms/search

Richiesta

ParametroObbligatorioTipoDescrizione
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

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

BAD_CREDENTIAL - credenziali non valide

NO_PARAMS - Nessun parametro valorizzato

BAD_ID - Parametro id non valido

BAD_MSISDN - Parametro msisdn non valido

BAD_DATE - Formato date non valido

BAD_STATUS - Parametro status non valido
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

CodiceDescrizione
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
      }
   ]
}