SMS Broadcast API (HTTP)

Updated 8 months ago by RM

Access

The API can be accessed via both HTTP GET and POST at the following URL (All fields must be URL encoded.) :

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

For GET requests the parameters must be specified in the URL. For example:

https://smsapi.telecomstats.co.uk/smsbatchapi/http/sendbatch/1?username=user%40email.com&password=XXXX&mobile=07123456789&message=This+is+a+text

POST requests can either be sent with the fields in the URL or with the fields specified in the form data of the request.

Fields

Field

Notes

username

The username for your API account

password

The password for your API account

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.

sender*

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, 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 optional parameter

 Return Values

An HTML message will be returned containing either a success message and the ID of your batch, or an error code.

Result

HTTP Status Code

Reason/Action

00 - Success

200 OK

Your batch was sent

11 - Username/Password incorrect

401 Unauthorised

Check your API credentials.

16 - Invalid request - variable 'mobile' not specified

400 Bad Request

The required field ‘mobile’ has not been provided.

17 - Invalid request - variable 'message' not specified

400 Bad Request

The required field ‘message’ has not been provided.

18 - Invalid Mobile Number - too short

400 Bad Request

The mobile number received is too short to be valid. Please check and retry.

19 - Invalid request - unable to parse

400 Bad Request

The request was not formed correctly and the server was unable to extract the data necessary to send the batch.

 

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. The delivery report will be in XML and 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 reformatted 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 delivery report:

Delivery Codes

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

Undelivered

10

Failed to send after 3 attempts

15

Invalid originator

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


How did we do?