It’s a very straightforward task to build a small script in PHP to utilise our SMS Gateway to send out text messages.

The benefit of integrating your SMS Gateway with Text Marketer is that we have the lowest cost per message of any company in the UK.

You can find a sample PHP script for our SMS Gateway here and with a few basic modifications of the user details you should be able to have your application integrated within minutes.

We do also provide code snippets for other languages;

• PHP code example
• Visual C#.Net Console
• Delphi/Pascal Interface
• .NET examples
• ASP examples
• REST examples

If you have any queries or questions, our friendly and highly experienced technical team will be happy to help you out.

After 11 years of building SMS Gateways in PHP and other programming lanuguages, we’re confident we can help you overcome any task.

In our REST API specification document we saw, in general terms, how to make a request to our REST SMS API and how to deal with the response. Here we provide you with some more concrete examples that you can copy & paste!

NOTE: You will want to add additional error checking to the examples below.

In each of the languages used here we create a request, send it, receive the response, and parse its contents.

PHP

Example for getting the number of credits:

$url = 'http://www.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// 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);
$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);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;

} else {
	// handle the error
	var_dump($responseBody);
}

Example for getting the list of delivery reports:

$url = 'http://www.textmarketer.biz/services/rest/deliveryReports';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// 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);
$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);
	$atts = $xml_obj->reports->attributes();
	$num_reports = (int) $atts->quantity;

	if ($num_reports > 0)
	{
		echo "$num_reports reports\n";
		$reports = array();
		foreach ($xml_obj->reports->report as $xml_report)
		{
			$atts = $xml_report->attributes();
			$name = (string) $atts->name;
			$updated = (string) $atts->last_updated;
			$reports[] = array('name'=>$name, 'modified'=>$updated);
		}
		// do something with the report details
		var_dump($reports);
	} else {
		echo 'No reports available';
	}
} else {
	// handle the error
	var_dump($responseBody);
}

Example for getting the details of a particular delivery report:

// TODO the URL will change according to the delivery report to retrieve...
$url = 'http://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_09-02-10';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// 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);
$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);

	$reportRows = array();
	foreach ($xml_obj->report->reportrow as $xml_reportRow)
	{
		$atts = $xml_reportRow->attributes();
		$mobile = (string) $atts->mobile_number;
		$updated = (string) $atts->last_updated;
		$msgID = (int) $atts->message_id;
		$status = (string) $atts->status;
		$reports[] = array('mobile'=>$mobile, 'modified'=>$updated, 'messageID'=>$msgID, 'status'=>$status);
	}
	// do something with the report details
	var_dump($reports);

} else {
	// handle the error
	var_dump($responseBody);
}

Example for sending an SMS:

$url = 'http://www.textmarketer.biz/services/rest/sms';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!

$data = array('message'=>'hello','mobile_number'=>'447777777777', '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);
}

Example for transferring credits:

<?php
/**
 * POST request on the 'credits' resource (credit transfer)
 */
$url = 'http://www.textmarketer.biz/services/rest/credits';
// for testing:
//$url = 'http://sandbox.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!! - the username of the account you're transferring FROM
$password = 'myAPIpassword'; // CHANGE THIS!!!
$targetAccountNumber = 0; // CHANGE THIS!!

$data = array('quantity'=>'1','target'=>$targetAccountNumber,
	'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)
{
 // success - you may want to read in the return data here to see how many credits were  left on each account

} else {
	// handle the error here
	// var_dump($responseInfo);
	// var_dump($responseBody);
}

?>

For more details on creating REST requests in PHP, see here.

Adding SMS as a communication method to a system is often very useful, for instance you don’t have issues with spam filtering, it doesn’t require the person to make an immediate response like a phone call, so it’s great for alerts and triggers. Another good application for SMS (text messaging) which is often over looked is the ability to use it as a method to update a system or retrieve information without needing any equipment other than a mobile phone, any one would work. This is done using a short code.

Consider this example:

You own a fictitious “temporary employment agency” with several hundred people on your books.  Your client has asked you to fulfill a specific job such as a receptionist. You send an SMS:

Receptionist cover required for 2 weeks 4 hr per day @ £10 per hr, location Bristol. Reply with “more 4567a” for more info.

The last bit (more 4567a) is the information that allows us to automate things, the keyword more is used to identify you, and the code would be a reference to the job. The potential candidate could then reply where by (in this case) you could :

1. Send more details from the job description
2. Update the database that this person is a likely candidate
3. The person has expressed interest in the receptionist job, we could make an assumption that they maybe interested in other receptionist jobs so you could start creating groups that could be used for later targeting.

Implementation

So how do we set up the SMS gateway and send messages? Fortunately it’s easy.
First you need an account (it’s free) and automated. You’ll get the user name and password you need plus you get some free sends. You will also need to ask for the API URL.

Next use the out bound API (sometimes called an SMS gateway) for your message. This is a simple HTTP GET request which can either be sent via http or https. You will need to url encode the message.
http://<request the url>?username=myUsername&password=myPassword&number=447777777777&message=Receptionist+cover+required+for+2+weeks+4+hr+per+day+%40+%C2%A310+per+hr%2C+location+Bristol.+Reply+with+%22more+4567a%22&orig=88802
You can try the above in any old browser.

There is an example class (in PHP 5) that would do this for you

Next we want to use the incoming response from the recipient

This is the bit where we need to speak to or email the company,  a keyword is required  (which is free) on the 88802 short code, in our example we are using the word “more”. You then supply Text Marketer with a URL on your domain that will get notified with the parameters once a response is received. For example www.mydomain.com/myscript.php

If the applicant replied with “more 4567a” you would receive an HTTP GET like this http://www.mydomain.com/myscript.php?number=4477777777&message=more+4567a&network=ORANGEUK

It is then up to you how you use this information, the example gives a few ideas.

It is recommended that you use the  RESTful version of the API which has largely superseded this document (you can do more with it). However if you want to get up and running quickly then it might still be the best way for you.

When you create a free account you can also use the Text Marketer API (sometimes known as a gateway).
The API uses simple HTTP GET requests to communicate with the Text Marketer gateway server. The requests allow you to send SMS’s through the system, you can also retrieve delivery reports discussed here.

HTTP GET Request Parameters

* optional parameter, discussed below.

URL ENCODING
You must url encode the orig and message parameters, if you dont do this you’ll get gateway failures or odd results.

SUPPORTED CHARACTERS
The GSM alphabet is a subset of ISO-8859-1. The SMS GSM characters we can support is documented here

CONCATENATION
If you exceed 160 characters you automatically covert to concatenation sending, this has the following connotations. Each message consists of a 153 character ‘chunk’ (not 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.

An Example HTTP GET Request

http://www.textmarketer.biz/gateway/?username=n&password=s&number=4477777777&message=test&orig=me&option=xml

This would send an SMS to 4477777777 from “me” with the message “test”, remember the username “n” and password “p” can be found un your account under the Text Response => API Settings menu option.

SSL (HTTPS) Support

The API also supports SSL, just use port 443 instead ( https:// )

Gateway Responses

The API or Gateway can respond in 2 formats depending if you have set the option=xml (recommended) or not.

No option parameter (or option blank).  Simple ‘plain text’ response

Once you have made a successful connection (HTTP 200) to our server and sent the request the server will reply in two different ways.

• SUCCESS <new line><number of credits remaining><new line>
• FAILED <new line> <reasons><number of credits remaining if available><new line>

The final line of the response contains the number of credits you have remaining, you get 10 free credits with your account.

A simple PHP 5 class for sending bulk SMS is available here

Using the option=xml (recommended)

A better way of decoding the response is to use the parameter option, this will make the gateway respond in the  XML format which gives room for future proofing and also it’s a better way to interpret / parse the results.

XML Example (success)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE response SYSTEM "http://www.textmarketer.biz/dtd/api_response.dtd">

<response status="success" id="1213465434">

    <credits>1000</credits>

   <credits_used>1</credits_used>

</response>

XML Example (failure)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE response SYSTEM "http://www.textmarketer.biz/dtd/api_response.dtd">

<response status="failed" id="0">

   <reason>invalid message or missing</reason>

   <reason>invalid number or too short</reason>

</response>
 

The DTD for the xml is available here. In reality it doesn’t get any more complicated than the above.

A simple PHP 5 class for sending bulk SMS is available here

Help and an example of our short code API

Help with ASP Bulk SMS

NET Examples

Supported and Unsupported characters in Text Messages – GSM Character Set

PHP 5 Delivery Report Helper Class for our SMS Gateway

PHP 5 SMS Send Class implementing listeners on our SMS Gateway

Using the SMS Gateway API, Automating Delivery Report Collection

Text Marketer short code API options