SMS Batch API – REST Interface Specification

Updated by Tech Support

SMS API Integration Details

This documentation is for the SMS Batch API - REST solution. This solution is provided to enable the sending of text messages.

In addition to this API Document you will also need your Account Manager to provide you with a Username & Password and to add some SMS Credits to your account for testing.

API Request

Requests must be as a POST to https://smsapi.telecomstats.co.uk/smsbatchapi/rest/sendbatch/1

Authentication

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

Content Format

Please set the content-type header field to one of these 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

 

Request Parameters

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*

The number or text to show as the sender of the message. If alphanumeric then this can be no more than 11 characters, for numeric senders then 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 then 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 then set this to 1 otherwise it will be assumed that your message is in plain text

validity*

How long until attempts to send the message end. In the format of <increment><m/h/d>. M = minutes, H = hours, D = days, not case sensitive.

A validity can be set up to a maximum of 3 days, if a validity of more than 3 days is specified then it will be set as 3 days.

E.g. to set a validity of 20 minutes then 20m. For 6 hours then 6h. For 2 days then 2d etc.

 * optional parameter

Response Format

Please set the Accept header field to one of these to specify a response format, if no Accept header is specified then the server will respond with XML by default

Format

Accept

XML

text/xml

JSON

text/json

HTML (table)

text/html

CSV

text/csv

 

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

Request Examples

XML submission:

<xml>    

<mobile>07123456789</mobile>    

<message>This is a test</message>    

<subject>Test</subject>

</xml>

 

JSON submission:

{

"mobile": "07123456789",    

"message": "This is a test",    

"subject": "Test"

}

Response Examples 

XML response

<xml xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">    

<batch>1234</batch>

</xml>

JSON response

{    

“batch”: “1234”

}

 

CSV response

batch,1234

An example HTML response

<HTML>

<BODY>

<TABLE>

<TR>

<TD>batch</TD>

<TD>1234</TD>

</TR>

</TABLE>

</BODY>

</HTML>

 

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.

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

Report Parameters

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

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

Undeliverable

10

Failed to send after 3 attempts

15

Invalid originator

Delivery Report Examples

An example XML delivery report:

<dr>

<batch_id>1234</batch_id>    

<mobile>447123456789</mobile>    

<report>success</report>    

<code>2</code>

</dr>

 

An example JSON delivery report:

{    

"batch_id":"1234",    

"mobile":"447123456789",    

"report":"success",    

"code":"2",    

"param1":null,    

"param2":null

}

Message Status Request

As an alternative to using a handler the status of any message sent can be request from the system.

This must be made via a GET request to:

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

Parameters for message status request

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

Example Request

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

Example Response

XML response

<xml xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">    

<batch>1234</batch>    

<param1 />    

<param2 />    

<reports>        

<report>            

<mobile>447123456789</mobile>

<code>2</code>             

<time>2020-06-03 13:38:49</time>            

<credits>1</credits>            

<status>success</status>        

</report>    

</reports>

</xml>

JSON response

{    

"batch": "1234",    

"param1": "",   

"param2": "",    

"reports": [{

"mobile": "447123456789",            

"code": "2",            

"time": "2020-06-03 13:38:49",            

"credits": "1",            

"status": "success"        

}]

}

 

HTML response

<HTML>

<BODY>

<TABLE>

<TR>

<TH>mobile</TH>

<TH>code</TH>

<TH>time</TH>

<TH>credits</TH>

<TH>status</TH>

</TR>

<TR>

<TD>447123456789</TD>

<TD>2</TD>

<TD>2020-06-02 09:49:53</TD>

<TD>1</TD>

<TD>success</TD>

</TR>

</TABLE>

</BODY>

</HTML>

 

CSV response

mobile,code,time,credits,status

447123456789,2,2020-06-02 09:49:53,1,success

 

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

402 PaymentRequired

Insufficient credits on your account

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?