Methods

Objects

SENDING SMS

Mobile Terminated (MT)

Send SMS all around the world with 200+ countries available!

Summary

    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

    Method

    $result = $api->call('sms.send', ['SMS', '+16469820800', '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', '+447890123456', 'Hello world!', None)
    
            

    Personalized sender


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

    Method

    $result = $api->call('sms.send', ['Your Brand', '+16469820800', 'Hello, SMS world!', null]);
    
    api.call('sms.send', 'Your Brand', '+33612345678', 'Hello world!', null);
    
    result = api.call('sms.send', 'Your Brand', '+447890123456', '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

    Method

    $result = $api->call('sms.send', ['', '+16469820800', 'Hello, SMS world!', null]);
    
    api.call('sms.send', '', '+16469820800', 'Hello world!', null);
    
    result = api.call('sms.send', '', '+33612345678', 'Hello world!', nil)
    
    result = api.call('sms.send', '', '+33612345678', '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.

    Method

    Objects

    • SMS.Options
    $options = new stdClass;
    $options->force_encoding = 'GSM'; // or 'UNICODE'
    
    $result = $api->call('sms.send', ['', '+33612345678', 'Hello, SMS world!', $options]);
    
    var optionSMS = { force_encoding: 'GSM' }; // or 'UNICODE'
    
    api.call('sms.send', '', '+33612345678', 'Hello world!', optionSMS);
    
    optionSMS = { :force_encoding => 'GSM' } # or 'UNICODE'
    
    result = api.call('sms.send', '', '+447890123456', '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.

    Method

    $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, 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', '+447890123456', 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', '+447890123456', 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.

    Method

    Objects

    • SMS.Options
    $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', '+16469820800', 'Hello world!', optionSMS);
    
    optionSMS = { :nature => 'ALERTING' } # or 'MARKETING'
    
    result = api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', optionSMS)
    
    optionSMS = { 'nature': 'ALERTING' } # or 'MARKETING'
    
    result = api.call('sms.send', 'SMS', '+16469820800', 'Hello world!', optionSMS)
    
            

    Custom data

    Method

    Objects

    • SMS.Options
    $options = new stdClass;
    $options->user_data = '42';
    
    $result = $api->call('sms.send', ['SMS', '+33612345678', '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', '+33612345678', 'Hello world!', optionSMS)
    
    optionSMS = { 'user_data': '42' }
    
    result = api.call('sms.send', 'SMS', '+447890123456', '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.

    Method

    Objects

    • Webhook
    $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.

    Method

    Objects

    • SMS.Options
    • Webhook
    $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', '+33612345678', 'Hello world!', optionSMS).success(function(response) {
        // success callback
    });
    
    optionSMS = {
        :webhook => {
            :endpoint => 'http://yourdomain.com/webhook_path',
        }
    }
    
    result = api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', optionSMS)
    
    optionSMS = {
        'webhook' {
            'endpoint': 'http://yourdomain.com/webhook_path',
        }
    }
    
    result = api.call('sms.send', 'SMS', '+447890123456', 'Hello world!', optionSMS)