Contact Us

SMS API Gateway

1. Description

With our FREE, simple Programmer Gateway you can send, receive & receipt SMS messages directly from your server, business application or website in minutes.

Whether you have a Short Code, Shared or Dedicated Inbound Number all inbound texts & replies will be forwarded instantly to your server (see here).

What’s more the use of our Programmer Gateway is FREE and so is our technical support.

2. Example Uses

The beauty of our Programmer Gateway is that you can build it into your business processes and so it can be used for virtually anything, however here are a few example uses:

• Appointment Reminders
  If your business functions around date specific events (e.g. MOT date, renewal dates, contract dates or appointment times) then you can use the API Gateway to automatically send out appointment reminders.
  
  
• 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
  With the Programmer Gateway texts can easily 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 SMS’ Button
  A simple ‘Send SMS’ button with template messages could be easily incorporated into you business programmes.
  
  
• 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.

3. Features & Benefits

4. Price

With our Programers API SMS service you only pay for the messages you send. There is no set-up fee or monthly contract.

You purchase bundles of credits. A credit allows you to send 1 text message to 1 person – so if you want to send 1 text message to 100 people you need 100 credits. Your credits last indefinitely and can be bought from your account using all major credit or debit cards. Larger bundles can be paid for by BACS or cheque by calling us on 0845 009 3180.

We give 10 FREE credits with every new account. So why not try us out – you have nothing to lose.

If you wish to purchase over 100,000 credits phone us on 0845 009 3180 for a very competitive quote based on your requirements.

5. Next Steps

Step 1 - Open an Online SMS account (if you haven’t already opened one – click here)

Step 2 - Implement the scripts below and off you go…

Step 3 - To start receiving SMS messages simply add the url to the "inbound section" of your account settings page.

Please remember 1 message sent to 1 person costs 1 credit – so you might want to top up your credits as well!

6. Send, Receive & Receipt SMS Texts

The HTTP POST API

HTTP POST can be used in all modern programming languages including ASP, ASP.NET, c++, c#, php, VB, VB.NET, command lines, SSH & cURL. The following section outlines how to send messages using either php or ASP. We can provide examples in other languages on request, simply Contact Us at support@txtlocal.com.

Meet the simple SMS API variables

info

A flag to switch on/off debug information. The following info is returned when info is set to 1:

Responses:
TestMode= 0 for live, 1 for testing (messages don't go to handset and credits not deducted)

MessageReceived= The received message

URLReceived= The received WAP PUSH URL (not required)

ScheduledDate= The received scheduled SMS time (not required)

Custom= The received custom ID to be passed back in receipt (not required)

From= The received SMS originator. Uses account default if blank

CreditsAvailable= Number of credits at start. You can also call http://www.txtlocal.com/getcredits.php, passing uname and pword to get a credit total.

MessageLength= Length of the message in characters

MessageCount= Number of messages (break at 160, 306, 459, 612)

NumberContacts= The number of comma separted numbers

CreditsRequired= Credits required for job (MessageCount * NumberContacts)

CreditsRemaining= Credits remaining after the job

Errors:
Error=No credit
Error=Not enough credit for send
Error=Invalid login
Error=Message Too Long (>612 characters)
Error=Message not sent. Please check your data - especially the numbers. Are they all in INTERNATIONAL format?

json

If you would prefer to use a more structured response than the line-by-line of info=1, then set info=0,json=1. This will return all the above information is JSON format. This can then be parsed in most modern languages.

test

This is the test mode. If test=1 then messages will not be sent and credits will not be deducted.

address

The url on the Txtlocal server where we receive your messages. This is static and can not be changed. Always use: www.txtlocal.com/sendsmspost.php - preferably using HTTP(s) for your own security.

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. For more prefixes click here.

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 (eg, http://www.google.com).

custom

This is not mandetory. If set, you can record a custom ID against the the message batch, which will be passed back in the delivery receipt.

rcpurl

This is not mandetory. 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 mandetory. 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.

Send Using PHP

This example uses the cURL library. Please ensure it is enabled on your server. If you can't use cURL then use sockets. See here.

<?php
//set up variables
$info = "1";
$test = "0";
$address = "www.txtlocal.com/sendsmspost.php";
$message = "Hello this is a test with an ampersand (&) and a £5 note";
$message = urlencode($message); //encode special characters (e.g. £,& etc)
$from = "Jims Autos";
$uname = "youremailaddress";
$pword = "yourpassword";
$selectednums = "447740101098";

//build url
$data = "uname=" . $uname . "&pword=" . $pword . "&message=" . $message . "&from=" . $from . "&selectednums=" . $selectednums . "&info=" . $info . "&test=" . $test;

//send messages
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"http://$address");
//curl_setopt($ch, CURLOPT_URL,"https://$address"); //secure connection
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
//curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //use this to suppress output
$result = curl_exec ($ch); //This is the result from Txtlocal - store as required
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 = "447740101098"

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
%>

Send Using C# .NET

<%@ 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.co.uk/sendsmspost.php");
}
private String readHtmlPage(string url)
{
String result = "";
String strPost =
"uname=youremail@domain.com&pword=yourpass&message=hello&from=SMITHS"+
"&selectednums=447740101097&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 = strPost.Length;
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>

Send Using ASP .NET

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", "447nnnnnnnnn", "")

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)

Send Using JAVA

import java.io.*;
import java.net.*;

public class HTTPAdaptor {

private static final String domain = "https://www.txtlocal.com/sendsmspost.php";
private static final String userName = "yourusername";
private static final String userPwd = "yourpassword";
private static final String from = "yourfromname";

public void sendSMS(String phoneNumber, String smsText) {
PrintWriter out = null;
try {
StringBuffer postParams = new StringBuffer();
postParams.append("uname=").append(userName).append("&");
postParams.append("pword=").append(userPwd).append("&");
postParams.append("message=").append(smsText.replaceAll(" ", "%20")).append("&");
postParams.append("from=").append(from).append("&");
postParams.append("selectednums=").append(phoneNumber).append("&");
postParams.append("info=1");

System.out.println("SMSGateway - Sending Message [msg:" + smsText + "] [ph:" + phoneNumber + "]");

System.out.println("Post == [" + postParams.toString() + "]");

URL url = new URL(domain + "?" + postParams.toString());
URLConnection conn = url.openConnection();
// conn.setDoOutput(true);

System.out.println("Connected to SMS Gateway");

BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;

while ((inputLine = in.readLine()) != null) {
System.out.println(inputLine);
}
in.close();

// conn.setRequestProperty("charset", "UTF-8");
// out = new PrintWriter(new OutputStreamWriter(conn.getOutputStream()));
//
//
// out.write(postParams.toString());

// out.flush();
// out.close();
conn = null;

System.out.println("All Done");
} catch (MalformedURLException mue) {
mue.printStackTrace();
} catch (IOException ioe) {
ioe.printStackTrace();
} finally {
try {
// if (out != null)
// out.close();
} catch (Exception e) {
}
}
System.out.println("Now we're really all done.");
}
}

Receive SMS

To receive an SMS message 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:

Sender

The mobile number of the handset

Content

The message content

inNumber

The number the message was sent to (your inbound number)

For Example: In PHP

$content = $_REQUEST["content"];
$sender = $_REQUEST["sender"];
$inNumber = $_REQUEST["inNumber"];

For Example: In ASP

content = Request.Form("content")
sender = Request.Form("sender")
inNumber = Request.Form("inNumber")

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).

For Example: In PHP

$number = $_REQUEST["number"];
$status = $_REQUEST["status"];
$customID = $_REQUEST["custom"];

For Example: In ASP

number = Request.Form("number")
status = Request.Form("status")
customID = Request.Form("custom")

We are here to help you with ANY queries. Please don’t hesitate to simply Contact Us at support@txtlocal.com and we usually respond within minutes!