SMS Broadcast APIs (REST)

Updated 1 year ago by RM

Access

The API can be accessed via POST only at the following URL:

https://smsapi.telecomstats.co.uk/smsbatchapi/rest/sendbatch/1

Authentication

Requests must contain a basic authentication header, containing your username and password.

Fields

Field

Notes

mobile

This can be a single mobile or a comma separated list.

Mobiles can be sent in UK format (i.e starting 07) but will be converted to international format (i.e starting 447) for sending.

message

A single SMS can be up to 160 characters long.

Messages over 160 characters will be sent as a multi-part message which is reassembled at the recipient’s mobile into one long message, but sent as chunks of up to 153 characters.

subject*

This is the number or text to show as the sender of the message. If alphanumeric, this can be no more than 11 characters. For numeric senders, the maximum is 16 digits.

If this is not specified, then the default for your account will be used.

encoding*

If you have hex encoded your message as anything other than UTF-8, the encoding used must be specified.

param1*

This allows you to store a reference for this message. This will be returned in the delivery receipt if a handler is specified.

param2*

This allows you to store a second reference for this message. This will be returned in the delivery receipt if a handler is specified.

handler*

This allows you to specify a URL to send delivery reports to.

hex*

If your message has been converted to hex, set this to 1 otherwise it will be assumed that your message is in plain text.

 * denotes an optional field

Content Format

Set the 'Content-Type' header field to one of the following in order to specify the format of the request:

Format

Content-Type

XML

application/xml

JSON

application/json

Form Values

application/x-www-form-urlencoded

 

Response Format

Set the 'Accept' header field to one of the following to specify a response format. If no 'Accept' header is specified, the server will respond with XML by default.

Format

Accept

XML

text/xml

JSON

text/json

HTML (table)

text/html

CSV

text/csv

 

An example XML submission:

An example JSON submission:

An example XML response:

 An example JSON response:

 

An example CSV response:

An example HTML response

  Return Codes

HTTP Status Code

Reason/Action

200 OK

Your batch was sent

400 Bad Request

Missing required field/incorrectly formed data

401 Unathorized

Invalid credentials

500 Internal Server Error

The server encountered an error processing the request

 

Delivery Reports

If a handler is specified in your request, the delivery report will be forwarded on to that URL via HTP POST.

If the accept header is set to text/json, then it will be sent as JSON otherwise the delivery report will be in XML.

The delivery report will contain the following fields:

Field

Description

batch_id

The Batch ID returned when the request was submitted.

mobile

The mobile number of the recipient. (If supplied in UK format this will have been re-formatted to international format.)

report

This will either be ‘Success’ or ‘Fail’,

code

A numeric code for more detail of delivery problems. (See Delivery Codes below.)

param1

The value sent as param1 when submitting the request.

param2

The value sent as param2 when submitting the request.

 

An example XML delivery report:

 

An example JSON delivery report:

 

Delivery Code

Description

2

Sent

3

Failed to send to SMS provider

4

Provider failed to send the message to the end user.

6

Provider rejected the message.

7

Expired

8

Undeliverable

10

Failed to send after 3 attempts

15

Invalid originator

Delivery reports will be attempted a maximum of 3 times, in the event your handler is down.

Message Status Request

Fields

Field

Notes

batch

The Batch ID returned when the request was submitted

mobile*

To see a specific message within the batch the mobile can be supplied

 * optional

To check the status of a batch or a specific message in a batch, a 'GET' request can be sent to the following URL:

https://smsapi.telecomstats.co.uk/smsbatchapi/rest/messagestatus/1

An example GET request:

https://smsapi.telecomstats.co.uk/smsbatchapi/rest/messagestatus/1?batch=1234

Return Values

Example XML response:

 

Example JSON response:

 

Example HTML response:

Example CSV response:

 Return Codes 

HTTP Status Code

Reason/Action

200 OK

Batch status returned

400 Bad Request

Missing required field/incorrectly formed data

401 Unathorized

Invalid credentials

404 Not Found

Could not find the specified batch (and mobile if provided).

500 Internal Server Error

The server encountered an error processing the request.

      

        

      


How did we do?