REST SMS Gateway API – sms resource

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

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.