Textlocal Logo

API Documentation

Send SMS

This command can be used to send text messages to either individual numbers or entire contact groups.

Resource URL

https://api.txtlocal.com/send/

Sample Request

<?php
	// Account details
	$apiKey = urlencode('Your apiKey');
	
	// Message details
	$numbers = array(447123456789, 447987654321);
	$sender = urlencode('Jims Autos');
	$message = rawurlencode('This is your message');

	$numbers = implode(',', $numbers);

	// Prepare data for POST request
	$data = array('apikey' => $apiKey, 'numbers' => $numbers, "sender" => $sender, "message" => $message);
 
	// Send the POST request with cURL
	$ch = curl_init('https://api.txtlocal.com/send/');
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	$response = curl_exec($ch);
	curl_close($ch);
	
	// Process your response here
	echo $response;
?>
<?php
	// Account details
	$apiKey = urlencode('Your apiKey');
	
	// Message details
	$numbers = urlencode('447123456789,447987654321');
	$sender = urlencode('Jims Autos');
	$message = rawurlencode('This is your message');

	// Prepare data for POST request
	$data = 'apikey=' . $apiKey . '&numbers=' . $numbers . "&sender=" . $sender . "&message=" . $message;
 
	// Send the GET request with cURL
	$ch = curl_init('https://api.txtlocal.com/send/?' . $data);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	$response = curl_exec($ch);
	curl_close($ch);
	
	// Process your response here
	echo $response;
?>
<?php
	require('Textlocal.class.php');

	$Textlocal = new Textlocal(false, false, 'your apiKey');

	$numbers = array(447123456789);
	$sender = 'Jims Autos';
	$message = 'This is your message';

	$response = $Textlocal->sendSms($numbers, $message, $sender);
	print_r($response);
?>

Caution: Some users opt to place their request inside a code loop, while testing we highly recommend setting the test parameter to true, as occasionally an infinite loop can occur and users can consume all their credits very quickly.

Parameters

sender Use this field to specify the sender name for your message. This must be at least 3 characters in length but no longer than 11 alphanumeric characters or 13 numeric characters. Sender names can also include full stop, &, underscore or hyphen. Sender name should be limited to your brand rather than a reference to the SMS content or user. If this is excluded, it will use the default sender name configured on your account.
message The message content. This parameter should be no longer than 765 characters. See Helpful Information for message length details. The message also must be URL Encoded to support symbols like &.
Login Parameters (Additional Information)
apiKey You can create these in your Messenger Control Panel (click here) for each application, and limit the usage of them by host IP Address.
Optional Parameters
numbers Comma-delimited list of mobile numbers in international format (i.e. 447123456789). Maximum of 10,000 numbers and error code 33 will be returned if exceeded.
group_id This parameter can be used in place of the numbers parameter in order to send to an entire contact group. This parameter should contain the ID of the relevant group, which can found either within Messenger (in the "Reports" - "Advanced Reports" - "List of Group ID's" section) or by running the get_groups command. Additionally group 5 contains "contacts" and group 6 contains "opt-outs".
simple_reply Set to true to enable the Simple Reply Service for the message. This will override any sender value, as a Simple Reply Service number will be used instead.
schedule_time This parameter can be used to specify a schedule date/time for your message, which should be provided in Unix timestamp format. Times should be provided in GMT.
receipt_url Use this field to specify an alternative URL to which the delivery receipt(s) will be sent. See handling receipts documentation.
custom This value will be set against the message batch and will passed back in the delivery receipts. This allows you to match delivery receipts to their corresponding messages.
optouts Can be set to true in order to check against your own opt-outs list and Textlocal's global opt-outs database. Your message will not be sent to numbers within these lists. If not provided defaults to false.
validity Can be set, up to 72 hours in advance, to say after which time, you don't want the message delivered. This should be in a Unix timestamp format.
unicode Set this value to true to specify that your message body will contain unicode characters. See Encoding/Decoding Unicode Documentation
tracking_links Set this value to true to specify that the message contains links and they should be converted to short links (trackable in messenger), Please note that links must be url encoded before being placed into the message
test Set this field to true to enable test mode, no messages will be sent and your credit balance will be unaffected. If not provided defaults to false

Note: While both numbers and group_id are optional parameters, one or the other must be included in the request for the message to be sent.

Note:You can also send Link Tracked Surveys out via the API . View Sending Surveys via the API for more information.

Note: To activate International Sending please contact Textlocal Support on 01244 573 247 or support@textlocal.com

Sample Response

{
	"balance":1162,
	"batch_id":123456789,
	"cost":2,
	"num_messages":2,
	"message":{
		"num_parts":1,
		"sender":"Jims Autos",
		"content":"This is your message"
	},
	"messages":[{
		"id":"1151346216",
		"recipient":447123456789
	},
	{
		"id":"1151347780",
		"recipient":447987654321
	}],
	"status":"success"
}
<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<balance>4755.7</balance>
	<batch_id>123456789</batch_id>
	<cost>2</cost>
	<num_messages>2</num_messages>
	<message>
		<num_parts>1</num_parts>
		<sender>YourName</sender>
		<content>This is your message</content>
	</message>
	<messages>
		<message>
			<id>1151348130</id>
			<recipient>447123456789</recipient>
		</message>
	</messages>
	<status>success</status>
</response>

Errors

Error Codes
4 No recipients specified.
5 No message content.
6 Message too long.
7 Insufficient credits.
8 Invalid schedule date.
9 Schedule date is in the past.
10 Invalid group ID.
11 Selected group is empty.
32 Invalid number format.
33 You have supplied too many numbers.
34 You have supplied both a group ID and a set of numbers.
43 Invalid sender name.
44 No sender name specified.
51 No valid numbers specified.

Warnings

Warning Codes
3 Invalid number.