Textlocal Logo

API Documentation

Send SMS via Bulk JSON API

We also offer a bulk JSON interface for sending different messages to multiple recipients in bulk. This option is perfect for mail-merging text. We recommend no more than 500 tags in each submission.

Resource URL

https://api.textlocal.in/bulk_json

Sample Request

<?php

$messages = array(
    // Put parameters here such as sender, force or test
    'sender' => "SampleName",
    'messages' => array(
        array(
            'number' => 918123456789,
            'text' => rawurlencode('This is your message')
        ),
        array(
            'number' => 918987654321,
            'text' => rawurlencode('This is another message')
        )
    )
);

// Prepare data for POST request
$data = array(
    'apikey' => 'Your API key',
    'data' => json_encode($messages)
);

// Send the POST request with cURL
$ch = curl_init('https://api.textlocal.in/bulk_json/');
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);

echo $response;
<?php

$textlocal = new Textlocal(false, false, 'Your apiKey');

$data = array(
    'messages' => array(
        array(
            'number' => 918123456789,
            'text' => 'This is your message'
        ),
        array(
            'number' => 918987654321,
            'text' => 'This is another message'
        )
    )
);

$data = json_encode($data);
$response = $textlocal->sendBulkSms($data);

echo json_encode($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

data The JSON payload. The only required parameter is “messages”, an array that must include both a “number” and “text” parameter for the message. Optionally it can include a “unicode” parameter if you wish to send the message in unicode, providing your account has unicode enabled.
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.
Data Parameters—Optional parameters that can be included in the JSON data payload
sender Use this field to specify the sender name which is pre-approved by DLT and Textlocal.
  • For promotional messages, sender name must be 6 numeric characters.
  • For transactional, service implicit/explicit messages, sender name must be 6 alpha characters.
scheduled This parameter can be used to specify a scheduled date/time for your message, which should be provided in Unix timestamp format. Times should be provided in GMT.
receiptUrl Use this field to specify an alternative URL to which the delivery receipt(s) will be sent. See handling receipts documentation.
force If included and set to false, this will not send any messages if 1 or more messages in the send fails for any reason. If not provided defaults to true.
optouts If included and set to false, this will prevent opt-outs being honoured on your account. If not provided defaults to true.
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.
send_channel Defaults to sms, See WhatsApp documentation to send WhatsApp messages

Sample Response

{
    "messages":[
        {
            "balance":1161,
            "batch_id":123456789,
            "cost":1,
            "num_messages":1,
            "message":{
                "num_parts":1,
                "sender":"TXTLCL",
                "content":"This is your message"
            },
            "receipt_url":"",
            "custom":"",
            "messages":[
                {
                    "id":1151347780,
                    "recipient":918123456789
                }
            ]
        },
        {
            "balance":1160,
            "batch_id":123456790,
            "cost":1,
            "num_messages":1,
            "message":{
                "num_parts":1,
                "sender":"INDMOB",
                "content":"This is your message"
            },
            "receipt_url":"",
            "custom":"",
            "messages":[
                {
                    "id":1,
                    "recipient":918987654321
                }
            ]
        }
    ],
    "balance_pre_send":1162,
    "total_cost":2,
    "balance_post_send":1160,
    "status":"success"
}

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.
15 Invalid JSON string.
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.
57 No messages found.
80 Invalid Template. The message given didn't match any approved templates on your account.
191 Schedule time is outside that allowed.
192 You cannot send message at this time.
204 Invalid message content.
314 One or more messages failed to send. No messages sent.
600 Invalid channel

Warnings

Warning Codes
3 Invalid number.