SENDING SMS

API init

require 'vendor/autoload.php'; // Composer

$api = new \CALLR\API\Client;
$api->setAuth(new \CALLR\API\Authentication\LoginPasswordAuth('login', 'password'));

var callr = require('callr');
var api = new callr.api(callr.loginPasswordAuth('login', 'password'));

require 'callr'
api = CALLR::Api.new('login', 'password')

import callr
api = callr.Api("login", "password")

        

Basic - without options

$result = $api->call('sms.send', ['SMS', '+33612345678', 'Hello world!', null]);

api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', null).success(function(response) {
    // success callback
});

result = api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', nil)

result = api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', None)

        

Personalized sender

Your sender must have been authorized and respect the sms_sender format.
"SMS" is always authorized.

$result = $api->call('sms.send', ['Your Brand', '+447890123456', 'Hello, SMS world!', null]);

api.call('sms.send', 'Your Brand', '+447890123456', 'Hello world!', null);

result = api.call('sms.send', 'Your Brand', '+33612345678', 'Hello world!', nil)

result = api.call('sms.send', 'Your Brand', '+447890123456', 'Hello world!', None)

        

If you want to receive replies, do not set a sender - we will automatically use an SMS number

$result = $api->call('sms.send', ['', '+447890123456', 'Hello, SMS world!', null]);

api.call('sms.send', '', '+16469820800', 'Hello world!', null);

result = api.call('sms.send', '', '+16469820800', 'Hello world!', nil)

result = api.call('sms.send', '', '+447890123456', 'Hello world!', None)

        

Force GSM encoding

The default behaviour is to send your SMS with GSM 7-bit encoding. However, if your text contains a character that is not in the GSM 7-bit charset (Basic Character Set), we will send it as 16-bit UCS-2 (UNICODE) - using 2 bytes per character.

You can however force the encoding to be used at any time, using the force_encoding property.

If you force a GSM encoding, we will try to convert non-GSM characters to GSM ones. « becomes ", € becomes e, etc. The full mapping is available when calling the method sms.get_gsm_charset_mapping.

Please note that whatever the encoding forced or used, you always send your text as a JSON string to our API, without any special processing. The charset is applied in our platform before sending to the carriers.

$options = new stdClass;
$options->force_encoding = 'GSM'; // or 'UNICODE'

$result = $api->call('sms.send', ['', '+16469820800', 'Hello, SMS world!', $options]);

var optionSMS = { force_encoding: 'GSM' }; // or 'UNICODE'

api.call('sms.send', '', '+16469820800', 'Hello world!', optionSMS);

optionSMS = { :force_encoding => 'GSM' } # or 'UNICODE'

result = api.call('sms.send', '', '+33612345678', 'Hello world!', optionSMS)

optionSMS = { 'force_encoding': 'GSM' } # or 'UNICODE'

result = api.call('sms.send', '', '+16469820800', 'Hello world!', optionSMS)

        

Concatenated SMS (availability depends on carrier)

We automatically handle concatenated SMS. The number of SMS parts billed will be set on the parts property of the SMS object. The object can be sent to you using Webhooks.

If your SMS is GSM 7-bit encoded:

• If it's equal to or less than 160 characters, it counts as 1 SMS.
• If it's more than 160 characters, the split is done every 153 characters.

If your SMS is UNICODE encoded:

• If it's equal to or less than 70 characeters, it counts as 1 SMS.
• If it's more than 70 characters, the split is done every 67 characters.

$text = 'Some super mega ultra long text to test message longer than 160 characters '.
        'Some super mega ultra long text to test message longer than 160 characters '.
        'Some super mega ultra long text to test message longer than 160 characters';

$result = $api->call('sms.send', ['SMS', '+33612345678', $text, null]);

var text = 'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters';

api.call('sms.send', 'SMS', '+447890123456', text, null);

text = 'Some super mega ultra long text to test message longer than 160 characters ' +
       'Some super mega ultra long text to test message longer than 160 characters ' +
       'Some super mega ultra long text to test message longer than 160 characters'
result = api.call('sms.send', 'SMS', '+16469820800', text, nil)

text = ('Some super mega ultra long text to test message longer than 160 characters ' +
       'Some super mega ultra long text to test message longer than 160 characters ' +
       'Some super mega ultra long text to test message longer than 160 characters')
result = api.call('sms.send', 'SMS', '+16469820800', text, None)

        

Specify your SMS nature (alerting or marketing)

Please note that limitations apply and vary from country to country when using SMS for marketing purposes.
Please refer to regulations in the countries you are targeting.

$options = new stdClass;
$options->nature = 'ALERTING'; // or 'MARKETING'

$result = $api->call('sms.send', ['SMS', '+16469820800', 'Hello, SMS world!', $options]);

var optionSMS = { nature: 'ALERTING' }; // or 'MARKETING'

api.call('sms.send', 'SMS', '+33612345678', 'Hello world!', optionSMS);

optionSMS = { :nature => 'ALERTING' } # or 'MARKETING'

result = api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', optionSMS)

optionSMS = { 'nature': 'ALERTING' } # or 'MARKETING'

result = api.call('sms.send', 'SMS', '+33612345678', 'Hello world!', optionSMS)

        

Custom data

$options = new stdClass;
$options->user_data = '42';

$result = $api->call('sms.send', ['SMS', '+447890123456', 'Hello, SMS world!', $options]);

var optionSMS = { user_data: '42' };

api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', optionSMS);

optionSMS = { :user_data => '42' }

result = api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', optionSMS)

optionSMS = { 'user_data': '42' }

result = api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', optionSMS)

        

Configure a Webhook - URL to receive delivery notifications (DLR)

To receive DLR notifications, you can use Webhooks. You need to subscribe to the webhook sms.mt.status_update.

$type = 'sms.mt.status_update';
$endpoint = 'http://yourdomain.com/webhook_path';
$options = null;

$result = $api->call('webhooks.subscribe', [ $type, $endpoint, $options ]);

var type = 'sms.mt.status_update';
var endpoint = 'http://yourdomain.com/webhook_path';
var options = null;

api.call('webhooks.subscribe', type, endpoint, options).success(function(response) {
    // success callback
});

type = 'sms.mt.status_update'
endpoint = 'http://yourdomain.com/webhook_path'
options = nil

result = api.call('webhooks.subscribe', type, endpoint, options)

type = 'sms.mt.status_update'
endpoint = 'http://yourdomain.com/webhook_path'
options = None

result = api.call('webhooks.subscribe', type, endpoint, options)

        

Returns a Webhook object.

You're all set! DLR will be sent to this Webhook.

An example of the data pushed is available on the Webhooks page.

Set DLR URL per SMS sent

To receive DLR notifications, you can subscribe globally to the webhook sms.mt.status_update (like above). You can also use a "dynamic" webhook like below. DLR will be sent to both the global Webhook and the dynamic Webhook. Replies to this MT will also be sent to this specific Webhook.

When using a dynamic Webhook, you only need to set endpoint and optionally options.

$options = new stdClass;
$options->webhook = new stdClass;
$options->webhook->endpoint = 'http://yourdomain.com/webhook_path';

$result = $api->call('sms.send', ['SMS', '+33612345678', 'Hello, SMS world!', $options]);

var optionSMS = {
    webhook: {
        endpoint: 'http://yourdomain.com/webhook_path'
    }
};

api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', optionSMS).success(function(response) {
    // success callback
});

optionSMS = {
    :webhook => {
        :endpoint => 'http://yourdomain.com/webhook_path',
    }
}

result = api.call('sms.send', 'SMS', '+33612345678', 'Hello world!', optionSMS)

optionSMS = {
    'webhook': {
        'endpoint': 'http://yourdomain.com/webhook_path',
    }
}

result = api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', optionSMS)