Invio SMS

> Invio SMS
> Invio SMS Bulk
> Invio SMS Binario
> Calcolo del preventivo di un invio SMS
> Annulla invio SMS
> Cerca SMS
> Gestione statusCallback
> Gestione notificationCallback

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

POST https://api.smshosting.it/rest/api/sms/send

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
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 (max 1000 numeri) 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 5.

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-ddTHH:mm:ssZ) alla quale sarà inviato il messaggio.Se non viene specificato alcun valore il messaggio viene inviato immediatamente.
Il carattere Z indica il timezone nel formato RFC 822 4-digit.(Per l'Italia +0200 durante l'orario estivo e +0100 nel restante periodo dell'anno)

Ad esempio:

2014-12-25T08: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 String

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

Gestione statusCallback
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_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
401 Credenziali non valide
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.
BLACKLIST - Il destinatario è stato inserito nella blacklist.

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/send \
-d "from=mrossi" \
-d "to=393480000000" \
-d "text=Test Sms"


HttpResponse sms_send_response = Unirest.post("https://api.smshosting.it/rest/api/sms/send")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393470000000")
        .field("text", "Ciao")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393470000000',
  'text' => 'ciao'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/sms/send', $headers, $body);


response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/send",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393470000000",
        "text": urllib.quote("ciao")
        }
    )


  String body = "";
  body = body + "&from=" + HttpUtility.UrlEncode(tbSmsSendFrom.Text);
  body = body + "&to=" + HttpUtility.UrlEncode(tbSmsSendTo.Text);
  body = body + "&group=" + HttpUtility.UrlEncode(tbSmsSendGroup.Text);
  body = body + "&text=" + HttpUtility.UrlEncode(tbSmsSendText.Text);
  body = body + "&date=" + HttpUtility.UrlEncode(tbSmsSendDate.Text);
  body = body + "&transactionId=" + HttpUtility.UrlEncode(tbSmsSendTransaction.Text);
  body = body + "&sandbox=" + tbSmsSendSandbox.Checked;
  body = body + "&statusCallback=" + HttpUtility.UrlEncode(tbSmsSendCallback.Text);
  body = body + "&encoding=" + HttpUtility.UrlEncode(tbSmsSendCallback.Text);

  HttpResponse jsonResponse = Unirest.post(tbSmsSendUrl.Text)
      .header("Content-Type", "application/x-www-form-urlencoded")
      .header("Accept", tbSmsSendAccept.Text)
      .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
      .body(body)
      .asString();



{
   "from":"mrossi",
   "text":"Test Sms",
   "transactionId":"d41ebeeb38b6a04818aa707818d3161e",
   "smsInserted":1,
   "smsNotInserted":0,
   "sms":[
      {
         "id":389310742,
         "to":"393412345678",
         "status":"INSERTED"
      }
   ]
}

Invio SMS Bulk

Modalità di invio sms asincrono da utilizzare con un numero elevato di destinatari (Più di 1000 destinatari per singola richiesta).

Una volta inviata la richiesta viene restituito un transactionId utile ad identificare sucessivamente gli sms.

Nel caso l'invio non possa essere completato a causa di un errore verrà inviata un'email contentente il codice di errore verificatosi

Nota: Se invii fino a 1000 destinatari per singola richiesta ti consigliamo di utilizzare la funzione di Invio SMS

URI

POST https://api.smshosting.it/rest/api/sms/sendbulk

Richiesta

I parametri della richiesta sono gli stessi di Invio SMS

Addizionalmente l'invio bulk prevede questi parametri

ParametroObbligatorioTipoDescrizione
transactionCallback No String

 URL al quale sarà inviata via HTTP una notifica con lo stato complessivo dell'invio

Gestione notificationCallback

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

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
401 Credenziali non valide
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

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/sendbulk \
-d "from=mrossi" \
-d "to=393480000000" \
-d "text=Test Sms"


HttpResponse sms_sendbulk_response = Unirest.post("https://api.smshosting.it/rest/api/sms/sendbulk")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393470000000")
        .field("text", "Ciao")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393470000000',
  'text' => 'ciao'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/sms/sendbulk', $headers, $body);


response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/sendbulk",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393470000000",
        "text": "ciao"
        }
    )


  String body = "";
   body = body + "&from=" + HttpUtility.UrlEncode(tbSmsSendbulkFrom.Text);
   body = body + "&to=" + HttpUtility.UrlEncode(tbSmsSendbulkTo.Text);
   body = body + "&group=" + HttpUtility.UrlEncode(tbSmsSendbulkGroup.Text);
   body = body + "&text=" + HttpUtility.UrlEncode(tbSmsSendbulkText.Text);
   body = body + "&date=" + HttpUtility.UrlEncode(tbSmsSendbulkDate.Text);
   body = body + "&transactionId=" + HttpUtility.UrlEncode(tbSmsSendbulkTransaction.Text);
   body = body + "&sandbox=" + tbSmsSendbulkSandbox.Checked;
   body = body + "&statusCallback=" + HttpUtility.UrlEncode(tbSmsSendbulkCallback.Text);
   body = body + "&encoding=" + HttpUtility.UrlEncode(tbSmsSendbulkEncoding.Text);

   HttpResponse jsonResponse = Unirest.post(tbSmsSendbulkUrl.Text)
       .header("Content-Type", "application/x-www-form-urlencoded")
       .header("Accept", tbSmsSendbulkAccept.Text)
       .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
       .body(body)
       .asString();



{
   "from":"mrossi",
   "text":"Test Sms",
   "transactionId":"e51ea840fc7276922ac61b733027301d"
}

Invio SMS Binario

Invio di un SMS con contenuto binario.

Note sulle lunghezza del messaggio:

La lunghezza massima di un singolo SMS binario è di 140 byte (280 caratteri espressi in formato esadecimale)

Specificando un testo più lungo verranno inviati SMS concatenati. Lo spazio a disposizione per gli SMS concatenati è di 134 byte per SMS (268 caratteri espressi in formato esadecimale)

URI

POST https://api.smshosting.it/rest/api/sms/sendbinary

Richiesta

I parametri della richiesta sono gli stessi di Invio SMS con le seguenti variazioni

ParametroObbligatorioTipoDescrizione
text Si String

Contenuto binario del messaggio espresso come stringa esadecimale.

Ogni byte deve essere rappresentato con un valore esadecimale di due caratteri.

Ad esempio:

0fc24abf3413ba
udh No String

Campo facoltativo contenente l'UDH (User Data Header) del messaggio in formato esadecimale.

Ad esempio:

00c34abf300311
pid No Integer

Campo facoltativo contenente l'id protocollo (Protocol identifier) da utilizzare in formato decimale.

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

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

BAD_TEXT_HEX - il testo non contiene un esadecimale valido

BAD_UDH_HEX - l'udh non contiene un esadecimale valido

BAD_PID - il pid non contiente un valore intero valido

GENERIC_ERROR - errore interno al server
401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Dati Invio

I dati di invio ritornati sono gli stessi di Invio SMS

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/sendbinary \
-d "from=mrossi" \
-d "to=393480000000" \
-d "text=0fc24abf3413ba"


HttpResponse sms_sendbulk_response = Unirest.post("https://api.smshosting.it/rest/api/sms/sendbinary")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393470000000")
        .field("text", "0fc24abf3413ba")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393470000000',
  'text' => '0fc24abf3413ba'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/sms/sendbinary', $headers, $body);


response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/sendbinary",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393470000000",
        "text": "0fc24abf3413ba"
        }
    )


  String body = "";
   body = body + "&from=" + HttpUtility.UrlEncode(tbSmsSendbinFrom.Text);
   body = body + "&to=" + HttpUtility.UrlEncode(tbSmsSendbinTo.Text);
   body = body + "&group=" + HttpUtility.UrlEncode(tbSmsSendbinGroup.Text);
   body = body + "&text=" + HttpUtility.UrlEncode(tbSmsSendbinText.Text);
   body = body + "&date=" + HttpUtility.UrlEncode(tbSmsSendbinDate.Text);
   body = body + "&transactionId=" + HttpUtility.UrlEncode(tbSmsSendbinTransaction.Text);
   body = body + "&sandbox=" + tbSmsSendbinSandbox.Checked;
   body = body + "&statusCallback=" + HttpUtility.UrlEncode(tbSmsSendbinCallback.Text);
   body = body + "&encoding=" + HttpUtility.UrlEncode(tbSmsSendbinEncoding.Text);

   HttpResponse jsonResponse = Unirest.post(tbSmsSendbinUrl.Text)
       .header("Content-Type", "application/x-www-form-urlencoded")
       .header("Accept", tbSmsSendbinAccept.Text)
       .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
       .body(body)
       .asString();



{
   "from":"mrossi",
   "text":"0fc24abf3413ba",
   "transactionId":"e51ea840fc7276922ac61b733027301d"
}

Calcolo del preventivo di un invio SMS

Calcolo del credito necessario per un invio SMS

URI

POST https://api.smshosting.it/rest/api/sms/estimate

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
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 (max 1000 numeri) separandoli con il carattere virgola ",".

Ad esempio:

393481234567 oppure 393481234567,393481234568,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 superai 160 caratteri vengono inviati più sms concatenati fino ad una massimo di 5.
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_TEXT - parametro text non valido

BAD_ENCODING - parametro encoding non valido

BAD_FROM - parametro from non valido

BAD_GROUP - parametro group non valido

NO_VALID_RECIPIENT - nessun valido destinatario

GENERIC_ERROR - errore interno al server
401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

Dati relativi al preventivo

ProprietàDescrizione
cost Costo dell'invio
userCredit Credito residuo dell'utente
smsCount Numero di sms da inviare

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/estimate \
-d "from=mrossi" \
-d "to=393480000000" \
-d "text=Test Sms"


HttpResponse sms_estimate_response = Unirest.post("https://api.smshosting.it/rest/api/sms/estimate")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("to", "393470000000")
        .field("text", "Ciao")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'to' => '393470000000',
  'text' => 'ciao'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/sms/estimate', $headers, $body);


response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/estimate",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "to": "393470000000",
        "text": "ciao"
        }
    )


  String body = "";
  body = body + "&from=" + HttpUtility.UrlEncode(tbSmsEstimateFrom.Text);
  body = body + "&to=" + HttpUtility.UrlEncode(tbSmsEstimateTo.Text);
  body = body + "&group=" + HttpUtility.UrlEncode(tbSmsEstimateGroup.Text);
  body = body + "&text=" + HttpUtility.UrlEncode(tbSmsEstimateText.Text);
  body = body + "&encoding=" + HttpUtility.UrlEncode(tbSmsEstimateEncoding.Text);

  HttpResponse jsonResponse = Unirest.post(tbSmsEstimateUrl.Text)
      .header("Content-Type", "application/x-www-form-urlencoded")
      .header("Accept", tbSmsEstimateAccept.Text)
      .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
      .body(body)
      .asString();



{
   "cost":0.095,
   "userCredit":15.484,
   "smsCount":2
}

Annulla invio SMS

Annulla l'invio di un SMS non ancora inviato.

Questo metodo è utile per annullare un invio differito

URI

POST https://api.smshosting.it/rest/api/sms/cancel

Richiesta

  Il "Content-Type" per le richieste POST deve essere "application/x-www-form-urlencoded"
ParametroObbligatorioTipoDescrizione
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

* È richiesto che almeno un parametro sia valorizzato

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

Parametri non validi

I possibili errorMsg sono:

NO_PARAMS - Nessun parametro valorizzato

BAD_ID - formato id non valido
401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

La chiamata ritorna la lista degli sms annullati.

Per il dettaglio delle proprietà di ogni singolo sms vedi la funzione Cerca Sms.

 Esempio:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/cancel \
-d "id=389451366"


HttpResponse sms_cancel_response = Unirest.post("https://api.smshosting.it/rest/api/sms/cancel")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .field("id", "419853396")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$data = array(
  'id' => '419853396'
);
$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('https://api.smshosting.it/rest/api/sms/cancel', $headers, $body);


response = unirest.post(
    "https://api.smshosting.it/rest/api/sms/cancel",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "id": "419853396"
        }
    )


  String body = "";
  body = body + "&id=" + HttpUtility.UrlEncode(tbSmsCancelId.Text);
  body = body + "&transactionId=" + HttpUtility.UrlEncode(tbSmsCancelTransaction.Text);

  HttpResponse jsonResponse = Unirest.post(tbSmsCancelUrl.Text)
      .header("Content-Type", "application/x-www-form-urlencoded")
      .header("Accept", tbSmsCancelAccept.Text)
      .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
      .body(body)
      .asString();



[
   {
      "id":389451366,
      "to":"393480000000",
      "text":"Test Sms",
      "from":"mrossi",
      "status":"NOSENT",
      "insertDate":"2014-01-16T13:46:11+0100",
      "transactionId":"1389876345449",
      "price":0.0
   }
]

Cerca SMS

Ricerca degli sms inviati.

URI

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

Richiesta

ParametroObbligatorioTipoDescrizione
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-ddTHH:mm:ssZ
Il carattere Z indica il timezone nel formato RFC 822 4-digit.(Per l'Italia +0200 durante l'orario estivo e +0100 nel restante periodo dell'anno)
toDate No String Data fino alla quale gli sms sono stati inviati in formato yyyy-MM-ddTHH: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:

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
401 Credenziali non valide
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-ddTHH:mm:ssZ

sentDate - data invio del messaggio nel formato yyyy-MM-ddTHH:mm:ssZ

deliveryDate - data consegna del messaggio nel formato yyyy-MM-ddTHH: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 --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/sms/search?fromDate=2011-01-01T00:00:00-0200


HttpResponse sms_search_response = Unirest.get("https://api.smshosting.it/rest/api/sms/search")
        .basicAuth(SMS_AUTH_KEY, SMS_SECRET_KEY)
        .queryString("id", "419853396")
        .asJson();


Unirest\Request::auth(SMS_AUTH_KEY, SMS_SECRET_KEY);

$headers = array(
  'Accept' => 'application/json'
);

$param = array(
  'id' => urlencode('419853396')
);

$response = Unirest\Request::get('https://api.smshosting.it/rest/api/sms/search', $headers, $param);

response = unirest.get(
    "https://api.smshosting.it/rest/api/sms/search",
    headers={
        "Accept": "application/json"
        },
    auth=(SMS_AUTH_KEY, SMS_SECRET_KEY),
    params={
        "id": urllib.quote("419853396")
        }
    )


  String queryString = "?";
  queryString = queryString + "&id=" + HttpUtility.UrlEncode(tbSmsSearchId.Text);
  queryString = queryString + "&transactionId=" + HttpUtility.UrlEncode(tbSmsSearchTransactionId.Text);
  queryString = queryString + "&msisdn=" + HttpUtility.UrlEncode(tbSmsSearchMsisdn.Text);
  queryString = queryString + "&fromDate=" + HttpUtility.UrlEncode(tbSmsSearchFromDate.Text);
  queryString = queryString + "&toDate=" + HttpUtility.UrlEncode(tbSmsSearchToDate.Text);
  queryString = queryString + "&status=" + HttpUtility.UrlEncode(tbSmsSearchStatus.Text);
  queryString = queryString + "&offset=" + HttpUtility.UrlEncode(tbSmsSearchOffset.Text);
  queryString = queryString + "&limit=" + HttpUtility.UrlEncode(tbSmsSearchLimit.Text);
  HttpResponse jsonResponse = Unirest.get(tbSmsSearchUrl.Text + queryString)
      .header("accept", cbSmsSearchAccept.Text)
      .basicAuth(tbAuth_key.Text, tbAuth_secret.Text)
      .asString();



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

Gestione statusCallback

Come gestire le chiamate di statusCallback inviate da SMSHosting all'url indicato in fase di invio.

Nel caso non si voglia gestire la statusCallback è possibile in ogni momento interrogare lo stato di uno o più messaggi inviato con la funzione cerca SMS.

URI

POST http(s)://yourcallbacklurl
ParametroTipoDescrizione
id String

Id interno del messaggio inviato
transactionId String

L'identificatore personale dell'invio.
to String

Il destinatario del messaggio.
status String

Lo stato del messaggio.

Questo parametro può essere valorizzato con DELIVERED (ossia SMS consegnato) o NOTDELIVERED (SMS non consegnalbile).
notificationDate String

Data (in formato yyyy-MM-ddTHH:mm:ssZ) di ricezione della notifica sullo stato. Il carattere Z indica il timezone nel formato RFC 822 4-digit.(Per l'Italia +0200 durante l'orario estivo e +0100 nel restante periodo dell'anno)

Risposta attesa

HTTP Status Code

CodiceDescrizione
200 ok.
Qualsiasi altro codice

Viene effettuato un nuovo tentativo di invio dello status per un massimo di 20 volte.

I possibili stati di un sms(campo status) sono

CodiceDescrizione
PENDING Sms in coda per l'invio
SENT Sms inviato all'operatore
NOSENT Sms non inviato all'operartore
DELIVERED Sms consegnato al cellulare del destinatario
NOTDELIVERED Sms non consegnato al cellulare

Gestione notificationCallback

Nell'invio bulk è possbile specificare un URL come parametro notificationCallback.

Verso tale URL smshosting effettuarà delle chiamate per notificare l'esito dell'invio una volta che questo si è concluso.

Le chiamate saranno effettuate in POST con content-type application/json e conterranno un json descritto nella seguente tabella

URI

POST http(s)://yourcallbacklurl
ParametroTipoDescrizione
transactionId String

transactionId identificativo dell'invio. Tale parametro viene ritornato anche della riposta immediata dell'invio bulk
status String

Stato dell 'invio

I possibili valori sono:

ERROR - Non è stato possbile inviare alcun SMS per un'errore generale.Fare riferimento al parametro errorMsg per il dettaglio

COMPLETED - L'invio è stato effettuato con successo. Verranno restituiti i dettagli per ogni singolo SMS

Nel caso ci sia un errore nell'invio (status in ERROR) verrano valorizzati questi campi

ParametroTipoDescrizione
errorMsg String

Il parameteo viene valorizzato nel caso di status in ERROR

I possibili errorMsg sono:

BAD_TEXT_PLACEHOLDER -  text contiene dei placeholder non sostituibili

NO_CREDIT - credito insufficiente per effetturare l'invio

NO_VALID_RECIPIENT - nessun valido destinatario

GENERIC_ERROR - errore interno al server

Esempio di risposta con invio in errore

{
   "status":"ERROR",
   "errorMsg":"NO_CREDIT",
   "transactionId":"1ccf2c63472387ede0dbbfef9996d2d4"
}

Nel caso l'invio vada a buon fine (status in COMPLETED) verrano valorizzati questi campi

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.
BLACKLIST - Il destinatario è stato inserito nella blacklist.

Esempio di risposta con invio completato

{
   "status":"COMPLETED",
   "from":"Mario",
   "text":"test",
   "transactionId":"e57ad82669d5bf96ac37d18994374d5b",
   "smsInserted":0,
   "smsNotInserted":1,
   "sms":[
      {
         "to":"39340000000",
         "status":"INSERTED",
         "id":421420576
      }
   ]
}