This blog post has been superseded with our website documentation
sms
This resource deals with sending SMS to customer.
This document is referred to by the REST SMS Gateway API – Specification Document.
Resource URI:
http://api.textmarketer.co.uk/services/rest/sms
Actions relating to sending SMS messages.
- POST method – Used to send an SMS message.
POST
POST method
Attempts to send the specified SMS message.
Example usage:
http://api.textmarketer.co.uk/services/rest/sms
Post arguments:
| parameter | usage |
| message | the content of the message to be sent, up to 612 characters (see Concatination below) in the GSM alphabet. The GSM alphabet is a subset of ISO-8859-1. The SMS GSM characters we can support is documented here |
| mobile_number | the mobile number of the recipient, in international format, e.g. 447777777777 |
| originator | a string or international mobile number of the sender to be displayed to the recipient |
| username* | (optional) required if not using HTTP Digest authentication |
| password* | (optional) required if not using HTTP Digest authentication |
* Can be found by logging in to your account, Settings->API Settings
CONCATENATION
CONCATENATION
If you exceed 160 characters you automatically invoke concatenation sending, this has the following consequences: Each message consists of a 153 character ‘chunk’, i.e. no longer 160 chars; the extra characters are used to glue the messages together. Therefore a message that is 307 characters long will require 3 messages to send (153 + 153 + 1).
Example POST response:
<response processed_date=”2010-03-23T10:31:39+00:00″>
<message_id>4172870907</message_id>
<credits_used>1</credits_used>
</response>
- message_id – the unique message ID attributed to the sent SMS
- credits_used – the number of credits used to send the SMS
Read the advanced specification of this response
.
Specific error codes:
| Code | Meaning |
| 0 | message refused by the operator |
| 1 | bad username or password |
| 2 | no more credits |
| 3 | invalid originator or too long |
| 4 | invalid or missing originator |
| 5 | invalid message or too long |
| 6 | you do not have enough credits for this message |
| 7 | invalid message or missing |
| 8 | message contains unsupported characters (listed in error message) |
| 9 | invalid number or too short |
| 10 | invalid number or not an integer |
CONCATENATION
Example XML error response:
<response processed_date=”2010-03-24T14:37:41+00:00″> <errors> <error code=”10″>invalid number or not an integer</error> <error code=”9″>invalid number or too short</error> </errors> </response>
Example PHP code:
<?php
/** * POST request on the ‘sms’ resource (send an SMS)
*/ $url = ‘http://api.textmarketer.co.uk/services/rest/sms’;
//$url = ‘http://sandbox.textmarketer.biz/services/rest/sms’;
$username = ‘myAPIusername’; // CHANGE THIS!!!
$password = ‘myAPIpassword’; // CHANGE THIS!!!
$data = array(‘message’=>’hello’,’mobile_number’=>’447777123123′, ‘originator’=>’me’,
‘username’=>$username, ‘password’=>$password);
$data = http_build_query($data, ”, ‘&’);
// we’re using the curl library to make the request
$curlHandle = curl_init(); curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody = curl_exec($curlHandle);
$responseInfo = curl_getinfo($curlHandle);
curl_close($curlHandle);
// deal with the response
if ($responseInfo[‘http_code’]==200)
{ $xml_obj = simplexml_load_string($responseBody);
// do something with the result
echo “Message ID: $xml_obj->message_id\n”;
echo “Credits used: $xml_obj->credits_used\n”;
var_dump($responseBody);
} else {
// handle the error
var_dump($responseInfo);
var_dump($responseBody);
}
?>
NOTE
It is important to understand the difference between the status of a message in a delivery report, and getting a success or failure when using the API to send a message. A ’success’ response from the SMS send only confirms that the number and message appear to be in the correct format – this does not mean that the number actually exists, or that the message was received by the recipient. Delivery reports, however, confirm to you what has actually happened to the sent message. See the deliveryReport resource.