SMS Batch API – REST Interface Specification
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 |
