SMS API Gateway
Our Programmers Interface is a simple programmer gateway which enables the automatic sending, receiving and receipt of SMS messages directly from a server, business application or website.
The API gateway is free to all Txtlocal customers, we provide the relevant programmer coding necessary to create the link between your server and the Txtlocal server so you can be up and running in 15 minutes.
Example Uses
There are thousands of example uses for SMS texting, here are just a few:
- Appointment Reminders
The API Gateway is perfect for date specific events where things like MOT reminders, renewal reminders or appointment reminders can be automatically sent out at specific dates and times. - Purchase Products
In conjunction with a Short Code, people can purchase products (e.g. ringtones, wallpapers etc.) by simply texting in the unique code for the product. - Website Data Capture Forms
Any business with a website could use this service. All they need to do is include a mobile data capture form on their website for customers to enter their mobile number to receive news updates from your company. An automatic reply can be sent out as soon as they sign up thanking them for their details. - Nearest Store Lookups
Working in conjunction with a Short Code a simple process can be built where customers text in their postcode and automatically receive a text back containing details of their nearest store. - Customer Contact Strategy
Texts can be incorporated into your customer contact strategy. For instance, a mortgage company could send out a text to its customers the moment their mortgage has been agreed. - Send Text Button
A simple ‘Send SMS’ button with template messages can easily be incorporated into business programmes.
Price Guide
Our feature-rich accounts give you a complete text message marketing package at affordable prices. Price Guide
Features & Benefits
Each account has full access to all our award winning Web SMS features. Below is a small selection of features you will receive, included for free in your account.
- Automatically Send Texts
- You can automatically send texts to individual or multiple selections directly from your server, business applications or website.
- Automatically Receive Texts
- Whether you have a Short Code, Shared or Dedicated Inbound Number all inbound texts will be forwarded directly onto your server.
- Automatically Receive Receipts
- We will pass a delivery receipt (Delivered, Invalid, Expired) to your web server for every message that you send. You can also view a receipt report within your Txtlocal account.
- Full 128 Bit SSL Encryption
- For your security all messages sent to and from our platform are encrypted using SSL HTTP(s), also know as “the yellow padlock” in your web browser
- Multiple Sender Names
- Your messages arrive on handsets from the name of your company. This can be changed for every message sent e.g. ‘Message receive from Sony’
- WAP URL
- In conjunction with a Short Code you can send back specific WAP URLs to download different products (e.g. ringtones or wallpapers) based on the reference used in the incoming text.
- Its FREE
- It costs you nothing!
Guidelines
The simple to use API lets you integrate the power ot Txtlocal in to your web-based application quickly and easily. The following section outlines how to send messages using a variety of programming languages. If you need assistance getting our API to work, we're happy to help.
To connect to the API, you can POST or GET your query to the URL http://www.txtlocal.com/sendsmspost.php
For added security, connect to the API over SSL - replace http with https in the above URL.
- info
- A flag to switch on/off debug information.
View debug information. - json
- If set to 1, this will return ‘info’ in JSON format.
- test
- This is the test mode. If test=1 then messages will not be sent and credits will not be deducted.
- message
- The text message body. This can be up to 612 characters in length. A single message is 160 characters, longer messages are 153 each (2=306,3=459,4=612). You can insert any merge data into this message from your database before submitting to txtlocal. To insert a newline character use %n.
- from
- The "From Address" that is displayed when the message arrives on handset. Can only be alpha numeric or space. Min 3 chars, max 11 chars.
- uname
- Your txtlocal.com username.
- pword
- Your txtlocal.com password.
- selectednums
- A comma separated list of international mobile numbers. Each number must be PURELY numeric, no + symbols or hyphens or spaces. The numbers must start with the international prefix. In UK this would be 447xxxxxxxxx. View international prefixes.
- url
- This is not mandatory. If set, you can send a WAP PUSH (mobile internet bookmark) to a mobile phone. Simply set to a valid url.
- custom
- This is not mandatory. If set, you can record a custom ID against the the message batch, which will be passed back in the delivery receipt.
- group
- This is not mandatory. If set, you can send to a precreated Txtlocal.com group. You can get the required group ID from the REPORTS section of the control panel. Duplicates and optouts will be removed.
- rcpurl
- This is not mandatory. Alternate receipt URL. Instead of using the receipt URL in the Txtlocal Account Settings, receipts will be sent to this URL.
- shed
- This is not mandatory. The scheduled message date/time. In the format YYYY-MM-DD-HH-MM-SS (e.g 2008-03-28-14-56-00). Scheduled messages can be viewed and deleted via your Txtlocal online account.
- validity
- This is not mandatory. The time at which you wish the message to expire if it has not been received by the phone (i.e. Phone out of signal range or turned off). In the format MMDDHHmm (It cannot be greater than 48hours in the future).
Code Examples
Below is a selection of code examples you can copy and modify to your own purpose. If you need any help, please feel free to contact us.
This example uses the cURL library, please ensure it is enabled on your server. If you can't use cURL then use sockets.
<?php
// Authorisation details
$uname = "youremailaddress";
$pword = "yourpassword";
// Configuration variables
$info = "1";
$test = "0";
// Data for text message
$from = "Jims Autos";
$selectednums = "440000000000";
$message = "Test with an ampersand (&) and a £5 note";
$message = urlencode($message);
// Prepare data for POST request
$data = "uname=".$uname."&pword=".$pword."&message=".$message."&from=".
$from."&selectednums=".$selectednums."&info=".$info."&test=".$test;
// Send the POST request with cURL
$ch = curl_init('http://www.txtlocal.com/sendsmspost.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch); //This is the result from Txtlocal
curl_close($ch);
?>
<%
info = 1
test = 0
message = "Hello this is a test with a £5 note and an ampersand (&) symbol"
message = Server.urlencode(message) 'encode special characters (e.g. £,& etc)
from = "Jims Autos"
address = "https://www.txtlocal.com/sendsmspost.php"
uname = "youremailaddress"
pword = "yourpassword"
selectednums = "440000000000"
url = address & "?uname=" & uname & "&pword=" & pword & "&message=" & message & "&from=" & from & "&selectednums=" & selectednums & "&info=" & info & "&test=" & test
set xmlhttp = CreateObject("MSXML2.ServerXMLHTTP")
xmlhttp.open "POST", url, false
xmlhttp.send ""
msg = xmlhttp.responseText
response.write(msg)
set xmlhttp = nothing
%>
<%@ Import Namespace="System.Net" %>
<%@ Import Namespace="System.IO" %>
<script language="C#" runat="server">
void Page_Load(Object Src, EventArgs E) {
myPage.Text = readHtmlPage("http://www.txtlocal.com/sendsmspost.php");
}
private String readHtmlPage(string url)
{
String result = "";
String strPost = "uname=email@domain.com&pword=yourpass&message=hello&from=SMITHS" + "&selectednums=440000000000&info=1";
StreamWriter myWriter = null;
HttpWebRequest objRequest = (HttpWebRequest)WebRequest.Create(url);
//add Proxy info if required
//objRequest.Proxy = WebProxy.GetDefaultProxy();
//objRequest.Proxy.Credentials = CredentialCache.DefaultCredentials; //uses logged on user
//objRequest.Proxy.Credentials = new System.Net.NetworkCredential("UserName", "Password"); // Alternative - specify the user and password to use
objRequest.Method = "POST";
objRequest.ContentLength = Encoding.UTF8.GetByteCount(strPost);
objRequest.ContentType = "application/x-www-form-urlencoded";
try{
myWriter = new StreamWriter(objRequest.GetRequestStream());
myWriter.Write(strPost);
}
catch (Exception e)
{
return e.Message;
}
finally {
myWriter.Close();
}
HttpWebResponse objResponse = (HttpWebResponse)objRequest.GetResponse();
using (StreamReader sr = new StreamReader(objResponse.GetResponseStream()) )
{
result = sr.ReadToEnd();
// Close and clean up the StreamReader
sr.Close();
}
return result;
}
</script>
Private Function SendSMS_txtLocal(ByVal Test As Boolean, _
ByVal From As String, _
ByVal Message As String, _
ByVal SendTo As String, _
ByVal URL As String) As String
' Send a message using the txtLocal transport
Const TransportURL As String = "http://www.txtlocal.com/sendsmspost.php"
Const TransportUserName As String = "me@myemail.com"
Const TransportPassword As String = "mypassword"
Const TransportVerbose As Boolean = True
Dim strPost As String
' Build POST String
strPost = "uname=" + TransportUserName _
+ "&pword=" + TransportPassword _
+ "&message=" + Message _
+ "&from=" + From _
+ "&selectednums=" + SendTo
If URL <> "" Then
strPost += "&url=" + URL
End If
If Test = True Then
strPost += "&test=1"
End If
If TransportVerbose = True Then
strPost += "&info=1"
End If
' Create POST
Dim request As WebRequest = WebRequest.Create(TransportURL)
request.Method = "POST"
Dim byteArray As Byte() = Encoding.UTF8.GetBytes(strPost)
request.ContentType = "application/x-www-form-urlencoded"
request.ContentLength = byteArray.Length
Dim dataStream As Stream = request.GetRequestStream()
dataStream.Write(byteArray, 0, byteArray.Length)
dataStream.Close()
' Get the response.
Dim response As WebResponse = request.GetResponse()
dataStream = response.GetResponseStream()
Dim reader As New StreamReader(dataStream)
Dim responseFromServer As String = reader.ReadToEnd()
' Clean up the streams.
reader.Close()
dataStream.Close()
response.Close()
' Return result to calling function
If responseFromServer.Length > 0 Then
Return responseFromServer
Else
Return CType(response, HttpWebResponse).StatusDescription
End If
End Function
------
To send a message:
SendSMS_txtLocal(False, "From", "Message", "440000000000", "")
Where the parameters are used as follows:
Test: True if this is a test only (no message is sent)
From: 11 Alpha-numeric characters
Message: Up to 612 characters
Number(s): Comma separated list of numbers in international format (44) followed by the mobile number, without the leading zero
URL: URL to use for WAP PUSH (if required)
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpMethod;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
* Class to help send SMS messages
* @author chris
*/
public class SmsHelper {
private static final Log logger = LogFactory.getLog( SmsHelper.class );
private static final String PARAM_USER = "uname";
private static final String PARAM_PASSWORD = "pword";
private static final String PARAM_MESSAGE = "message";
private static final String PARAM_SENDER = "from";
private static final String PARAM_PHONE_NO = "selectednums";
private static final String PARAM_INFO = "info";
/**
* Send an SMS message via the gateway.
* Returns whether or not the message could be successfully sent.
* @param sender
* @param phoneNumber
* @param smsText
* @return
*/
public static boolean sendSMS(final String sender, final String phoneNumber, final String smsText) {
try {
final HttpClient client = new HttpClient();
final HttpMethod method = new GetMethod("https://www.txtlocal.com/sendsmspost.php");
method.setQueryString(new NameValuePair[]{
new NameValuePair(PARAM_USER, "myUsername"),
new NameValuePair(PARAM_PASSWORD, "myPassword"),
new NameValuePair(PARAM_MESSAGE, smsText),
new NameValuePair(PARAM_SENDER, sender),
new NameValuePair(PARAM_PHONE_NO, phoneNumber),
new NameValuePair(PARAM_INFO, "1"),
});
final int statusCode = client.executeMethod(method);
logger.debug("SmsHelper: QueryString>>> "+method.getQueryString());
logger.info("SmsHelper: Status Text>>>"+HttpStatus.getStatusText(statusCode));
return true;
} catch (final Exception e) {
logger.error("Exception sending SMS: "+e.toString());
return false;
}
}
public static void main(final String[] args) {
sendSMS(args[0]/*sender*/, args[1]/*mobileNo*/, args[2]/*message*/);
}
}
We have a Python script that you can download and configure to send messages through your Txtlocal account.
Download now (sendsms.py - 4KB)
Note: you may need to right-click on the link, and save it to your computer.
We also offer a bulk XML interface for sending different message text to multiple numbers in bulk (great for bulk appointment reminders where each message contains different text):
- Post to: http://www.txtlocal.co.uk/xmlapi.php
- 1 SMS tag per submission (1 FROM per submission)
- Multiple Msg tags
- ID = a custom ID (if required)
- rcpurl = a custom receipt URL (if different to control panel default)
In PHP:
<?
$xmlData = '<?xml version="1.0" encoding="ISO-8859-1"?>
<SMS>
<Account Name="yourusername" Password="yourpassword">
<Sender From="Site 3">
<Messages>
<Msg ID="15" Number="440000000000">
<Text>Please come for you appointment tomorrow morning at 12:45</Text>
</Msg>
<Msg ID="16" Number="440000000000">
<Text>Please come for you appointment tomorrow morning at 14:00</Text>
</Msg>
</Messages>
</Sender>
</Account>
</SMS>';
$post = 'data='. urlencode($xmlData);
$url = "http://www.txtlocal.co.uk/xmlapi.php";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST ,1);
curl_setopt($ch, CURLOPT_POSTFIELDS ,$post);
curl_setopt($ch, CURLOPT_RETURNTRANSFER ,1);
$data = curl_exec($ch);
curl_close($ch);
echo $data;
?>
We do basic checks to ensure that username and password are correct, and calculate if there are sufficient message credits for the job. If either is false we simply return:
echo "Error=Invalid login";
or
echo "Error - insufficient credits. You need: " . $totalcost;
If your FROM is too long (>11) or too short (<3) it will default to whatever is your primary FROM address on your account.
Receive SMS
To receive an SMS message to your platform, simply add the URL address of the script on your webserver using the Txtlocal Control Panel 'Inbox Settings' pages. We will POST the following variables to you.
- sender
- The mobile number of the handset.
- content
- The message content.
- inNumber
- The number the message was sent to (your inbound number).
- Any email address extracted.
- credits
- The number of credits remaining on your Txtlocal account.
For example, in PHP:
<?php
$sender = $_REQUEST['sender'];
$content = $_REQUEST['content'];
?>
Receipt SMS
To receive an SMS message receipt to your platform, simply add the URL address of the script on your webserver using the Txtlocal account settings page. We will POST the following variables to you.
Note: you can include *#* within the URL and it will be replaced by the custom field.
- number
- The mobile number of the handset.
- status
- The message status. Either D for delivered, I for invalid or U for undelivered after 72 hours.
- customID
- The custom value passed during message send (if used).
