Sending SMS | SmsHosting.it
icon_qa
INTRODUZIONE API REST

Usi l'app Postman?
 

SENDING SMS

SMS Sending

Sending a text message to one or more recipients or groups in your address book.

You can test sending setting the sandbox parameter to true in the request.

The parameter statusCallback allows you to record a URL for status notification. SmsHosting will make an asynchronous HTTP request with the final sms status (Delivered, Not Delivered).

For more information, please refer to the parameters table below.

URI

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

Request

  "Content-Type" for POST requests must be "application/x-www-form-urlencoded"
ParameterMandatoryTypeDescription
from No String

The sender of the SMS.

It can be a valid phone number or an alphanumeric string of 11 characters. If not specified, the default profile sender is used.

 

to

No

(Required setting at least one of the fields to and group )

String

The recipient of the message.

Must be a cell phone number including the international code.
You can specify multiple phone numbers, separated by the comma character ",".

For example:

393481234567 or 393481234567,393481234568,393481234568

group

No

(Required setting at least one of the fields to and group )

String

Id of the group in Address Book that contain recipients

You can specify multiple contact groups, separated by the comma character ",".

For example, if you are heading nellla groups Friends (id = 1) and School (id = 2), you can specify:

1 or 1,2

text Yes String

Body of the text message

If the message exceeds 160 characters SMS chained are sent up to a maximum of 5.

date No String

Scheduled Sms

Date ( format yyyy-MM-dd'T'HH:mm:ssZ) on which the message will be sent. If you do not specify a value, the message is sent immediately.

example:

2014-12-25'T'08:00:00+0200 represent 25/12/2014 at 08:00:00 on GMT +2

transactionId No String

a personal identifier to mark the sending

Allows you to assign to all the sms sent with a call to the same identifier in order to use this parameter to get the status of messages. maximum 60 characters

sandbox No Boolean

Allows you to test the call without actually sending the message.

Useful parameter in development phase with REST API.

Admitted values true/false

statusCallback No String  CallBack URL for Delivery Receipt to which we will send a delivery receipt (Delivered, Not Delivered) for current SMS submissions.
encoding No String

The encoding to use for the text of the message.

Admitted values are:

7BIT - Encoding standard for GSM messages. The maximum length for a single text message is 160 characters .

UCS2 - 8-bit Encoding to send messages containing non-ASCII characters. The maximum length for a single text message is 70 characters.

AUTO - The encoding is automatically recognized based on the contents of the message text.

Default : 7BIT

Response

HTTP Status Code

CodeDescription
200 ok
400

invalid parameters

Possible errorMsg are:

BAD_TRANSACTIONID - invalid parameter transactionId

BAD_DATE - bad format date

BAD_TEXT - invalid parameter text

BAD_CALLBACK - invalid parameter statusCallback

BAD_ENCODING - invalid parameter encoding

BAD_FROM - invalid parameter from

BAD_GROUP - invalid parameter group

BAD_CREDIT - insufficient credit to send messages

NO_VALID_RECIPIENT - no valid recipients

GENERIC_ERROR - generic server error

401 Bad credentials
405 HTTP method not allowed
500 Generic error

Input data

PropertyDescription
from Sender address may be alphanumeric or international format number
text

Body of the text message.

If the message got over 160 characters (7BIT) or 70 characters (UCS2) SMS chained will be generated up to a maximum of 5.

transactionId

sending identifier

If not specified a transactionId will be automatically generated by the REST API

smsInserted Total number of sms inserted
smsNotInserted Total number of sms not inserted
sms

sms list

Each sms is described by properties:

to - recipients number

id - unique id assigned from server to sms .This value is useful to request the message status using the function SMS Search

status - Message status. Valued at INSERTED if the message is properly inserted, NOT_INSERTED otherwise.

statusDetail - if the message is not queued (status = NOT_INSERTED) this field contains a message explaining the error occurred.
The possible values ​​are:
BADNUMBERFORMAT - bad recipient number
DUPLICATESMS - Sms skipped by ANTISPAM because already inserted in the last 24 hours with the same recipient, sender and text (this ANTISPAM filter could be disabled with a request to customer support ).

 Example:

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"
{
   "from":"mrossi",
   "text":"Test Sms",
   "transactionId":"d41ebeeb38b6a04818aa707818d3161e",
   "smsInserted":1,
   "smsNotInserted":0,
   "sms":[
      {
         "id":389310742,
         "to":"393412345678",
         "status":"INSERTED"
      }
   ]
}

SMS Sending cost estimation

Calculation of the credit needed for SMS sending

URI

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

Request

  "Content-Type" for POST requests must be "application/x-www-form-urlencoded"
ParameterObbligatorioTipoDescription
from No String

The sender of the SMS.

It can be a valid phone number or an alphanumeric string of 11 characters. If not specified, the default profile sender is used.

 

to

No

(Required setting at least one of the fields to and group )

String

The recipient of the message.

Must be a cell phone number including the international code.
You can specify multiple phone numbers, separated by the comma character ",".

For example:

393481234567 or 393481234567,393481234568,393481234568

group

No

(Required setting at least one of the fields to and group )

String

Id of the group in Address Book that contain recipients

You can specify multiple contact groups, separated by the comma character ",".

For example, if you are heading nellla groups Friends (id = 1) and School (id = 2), you can specify:

1 or 1,2

text Yes String

Body of the text message

If the message exceeds 160 characters SMS chained are sent up to a maximum of 5.

encoding No String

The encoding to use for the text of the message.

Admitted values are:

7BIT - Encoding standard for GSM messages. The maximum length for a single text message is 160 characters .

UCS2 - 8-bit Encoding to send messages containing non-ASCII characters. The maximum length for a single text message is 70 characters.

AUTO - The encoding is automatically recognized based on the contents of the message text.

Default : 7BIT

Response

HTTP Status Code

CodeDescription
200 ok
400

invalid parameters

Possible errorMsg are:

BAD_TEXT - invalid parameter text

BAD_ENCODING - invalid parameter encoding

BAD_FROM - invalid parameter from

BAD_GROUP - invalid parameter group

NO_VALID_RECIPIENT - no valid recipients

GENERIC_ERROR - generic server error

401 Bad credentials
405 HTTP method not allowed
500 Generic error

Data relating to quote

PropertyDescription
cost credit needed for sms sending
userCredit user credit available

 Example:

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"
{
   "cost":0.095,
   "userCredit":15.484
}

Cancel SMS sending

Cancel SMS sending that is not yet posted to operator.

This method is useful to cancel a scheduled SMS

URI

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

Request

  "Content-Type" for POST requests must be "application/x-www-form-urlencoded"
ParameterManadatoryTypeDescription
id No * String

message internal Id

You can specify multiple id , separated by the comma character ",".

Example:

12312 or 432432,543543,435435

transactionId

No *

String TransactionId assigned to sms sending

* at least one param is mandatory

Risposta

HTTP Status Code

CodeDescription
200 ok
400

Invalid parameters

Possible errorMsg are:

NO_PARAMS - none of the parameters is setted

BAD_ID - bad format fieldid

401 Bad credentials
405 HTTP method not allowed
500 Generic error

The call returns the list of sms canceled.

For details about properties of each sms check the function Sms Search.

 Example:

curl --user AUTH_KEY:AUTH_SECRET -XPOST https://api.smshosting.it/rest/api/sms/cancel \
-d "id=389451366"
[
   {
      "id":389451366,
      "to":"393480000000",
      "text":"Test Sms",
      "from":"mrossi",
      "status":"NOSENT",
      "insertDate":"2014-01-16T13:46:11+0100",
      "transactionId":"1389876345449",
      "price":0.0
   }
]

SMS Search

Research of SMS messages sent.

URI

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

Request

ParameterMandatoryTipoDescription
id No * String

message internal Id

You can specify multiple id , separated by the comma character ",".

Example:

12312 oppure 432432,543543,435435

transactionId

No *

String TransactionId assigned to sms sending
msisdn

No *

String recipient GSM number
fromDate No * String start of date interval (sent date)with format yyyy-MM-dd'T'HH:mm:ssZ
toDate No String end of date interval (sent date)with format yyyy-MM-dd'T'HH:mm:ssZ
status No * String sms status (PENDING / SENT / NOSENT / DELIVERED / NOTDELIVERED)
offset No Integer

index of first result returned

Example:

If the search finds 100 text messages, and the field offset is set with value 50 and the field limit is set with value 10 the result contains text messages from 51 to 60.

Default : 0

limit No Integer

Number of items returned

Default : 20

* at least one param is mandatory

Response

HTTP Status Code

CodeDescription
200 ok
400

invalid parameters

Possible errorMsg are:

NO_PARAMS - none of the parameters is setted

BAD_ID - invalid parameter id

BAD_MSISDN - invalid parameter msisdn

BAD_DATE - Bad date format

BAD_STATUS - invalid parameter status

401 Bad credentials
405 HTTP method not allowed
500 Generic error

The response return a list of sms sent

PropertyDescription
smsList

List of text messages sent

Each sms have the following properties:

id - sms internal id

to - sms recipient

text - body of the text message

from - sender of the SMS

status - sms status. view table below.

insertDate - sms queued date with format yyyy-MM-dd'T'HH:mm:ssZ

sentDate - sms send date with format yyyy-MM-dd'T'HH:mm:ssZ

deliveryDate - sms delivered date with format yyyy-MM-dd'T'HH:mm:ssZ

transactionId - sending identifier

price - credit used for sending

metadata

Metadata useful for pagination

For further details on pagination visit reserved page

Possible sms status (field status) are:

CodeDescription
PENDING Sms queued for sending
SENT Sms sent to network operator
NOSENT Sms not sent to network operator (final status)
DELIVERED Sms delivered to recipient SIM (final status)
NOTDELIVERED Sms not delivered to recipient SIM (final status)

 Example:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/sms/received/search?fromDate=2011-01-01'T'00:00:00-0200
{
   "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
      }
   ]
}