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.textlocal.in/send/

Sample Request

<?php
	// Account details
	$apiKey = urlencode('Your apiKey');
	
	// Message details
	$numbers = array(918123456789, 918987654321);
	$sender = urlencode('TXTLCL');
	$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.textlocal.in/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('918123456789,918987654321');
	$sender = urlencode('TXTLCL');
	$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.textlocal.in/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(918123456789);
	$sender = 'TXTLCL';
	$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 If you have a promotional account, do not send this parameter. If you have a transactional account, use this field to specify the sender name for your message. Sender name must be 6 alpha characters and should be pre-approved by Textlocal. In the absence of approved sender names, use the default 'TXTLCL'
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. 918123456789). 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".
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.

Sample Response

{
	"balance":1162,
	"batch_id":123456789,
	"cost":2,
	"num_messages":2,
	"message":{
		"num_parts":1,
		"sender":"TXTLCL",
		"content":"This is your message"
	},
	"messages":[{
		"id":"1151346216",
		"recipient":918123456789
	},
	{
		"id":"1151347780",
		"recipient":918987654321
	}],
	"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>918123456789</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.
191 Schedule time is outside that allowed.
192 You cannot send message at this time.

Warnings

Warning Codes
3 Invalid number.