Methods

Objects

SENDR SMS Campaigns

Use the power of the SENDR API to create and manage campaigns

Create campaigns and get detailed reports, all through our JSON-RPC API.

Use all the same features than in our SENDR user interface through our API. Upload addressbooks, link them to campaigns and begin mass sending messages to your clients now.

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")
    
            

    Create and upload an addressbook


    Host a CSV or XLS file on a server and provide us with the URL so we can import it on our platform. Maximum file size is 10MB.

    
    $webhook = new stdClass;
    $webhook->endpoint = 'http://yourdomain.com/endpoint';
    
    // Returns a Job ID, POST request made to webhook endpoint when import job is done.
    $result = $api->call('media.import_file_from_url_async', ['http://yourdomain.com/addressbook.csv', $webhook]);
    
    // ...
    $phoneNumbersColumn = 3;
    $addressbook = $api->call('sendr/10/addressbook.create', ['My Address Book', 'Description']);
    
    // when returned Job is done, addressbook content is set from imported file if correctly formatted
    // $importData = POST data recieved on webhook endpoint when import is done
    $result = $api->call(
        'sendr/10/addressbook.append_file_async',
        [$addressbook->hash, $importData->result->filename, $phoneNumbersColumn, 'FR', $webhook]
    );
    
    
    // partial webhook object to recieve status updates
    var webhook = {
        'endpoint': 'http://yourdomain.com/endpoint'
    };
    
    // Returns a Job ID, POST request made to webhook endpoint when import job is done.
    api.call('media.import_file_from_url_async', 'http://yourdomain.com/addressbook.csv', webhook).success(function (){
        // ... success callback
    });
    
    // ...
    api.call('sendr/10/addressbook.create', 'My AddressBook', 'Description').success(function addressBookCreated(ab) {
        var phoneNumbersColumn = 3;
    
        // var importData = POST data recieved on webhook endpoint when import is done
        api.call('sendr/10/addressbook.append_file_async', ab.hash, importData.result.filename, phoneNumbersColumn, 'FR', webhook).success(function () {
            // when returned Job is done, addressbook content is set from imported file.
        });
    });
    
            

    Get a new campaign object


    To create a new campaign, it is easier to start from a partial pre-configured object generated from our API.

    
    $campaign = $api->call('sendr/10/campaign.get_object_template', ['SMS_SIMPLE']);
    
    
    api.call('sendr/10/campaign.get_object_template', 'SMS_SIMPLE').success(function (campaign) {
        // ...
    });
    
            

    You will receive a partial campaign object like the following:

    
    {
        "type": "SMS_SIMPLE",
        "name": "",
        "options": {
          "optout_enabled": false,
          "optout_blacklist": "",
          "nature": "MARKETING",
          "send_report": {
            "enabled": false,
            "emails": [],
            "phones": []
          }
        },
        "ivr": {
          "text": "",
          "encoding": "GSM",
          "sender": "",
          "optout_suffix": "",
          "optout_confirmed": ""
        },
        "addressbook": {
          "hash": ""
        },
        "blacklist": {
          "method": "ALL",
          "selected": []
        },
        "schedule": {
          "enabled": false,
          "timezone": "Europe/Brussels",
          "days": {}
        },
        "is_archived": false
      }
    
            

    Customizing campaign


    Let's edit our partial object to fit our needs and check the assigned values for errors.

    Object

    • Sendr.10.Campaign

    Method

    
    // $campaign = partial object from last step
    // $addressbook = addressbook object created in first step
    
    // Setting a name
    $campaign->name = "My CALLR Campaign";
    
    // Adding some content to our SMS and a sender
    $campaign->ivr->text = "This is a test message";
    $campaign->ivr->sender = "SMS";
    
    // Setting optouts messages
    $campaign->options->optout_enabled = true;
    $campaign->ivr->optout_suffix = "Send STOP to XXXXX to opt-out.";
    $campaign->ivr->optout_confirmed = "Your opt-out request has been registered.";
    
    // Linking our campaign to our addressbook
    $campaign->addressbook->hash = $addressbook->hash;
    
    // We want to get reports mailed
    $campaign->options->send_report->enabled = true;
    $campaign->options->send_report->emails = ["you@yourdomain.com"];
    
    // Lastly, we want to add some scheduling options
    // We want to pause the campaign each Monday and Thursday between 12:00 and 14:30.
    $scheduleDays = new stdClass();
    $scheduleDays->mon = [
        (object)['action' => 'pause', 'hour' => '12:00'],
        (object)['action' => 'unpause', 'hour' => '14:30']
    ];
    $scheduleDays->thu = [
        (object)['action' => 'pause', 'hour' => '12:00'],
        (object)['action' => 'unpause', 'hour' => '14:30']
    ];
    
    $campaign->schedule->enabled = true;
    $campaign->schedule->days = $scheduleDays;
    
    // Checking our campaign object for errors
    $errors = $api->call('sendr/10/campaign.check', [$campaign]);
    
    
    
    // var campaign = partial object from last step
    // var addressbook = addressbook object created in first step
    
    // Setting a name
    campaign.name = "My CALLR Campaign";
    
    // Adding some content to our SMS and a sender
    campaign.ivr.text = "This is a test message";
    campaign.ivr.sender = "SMS";
    
    // Setting optouts messages
    campaign.options.optout_enabled = true;
    campaign.ivr.optout_suffix = "Send STOP to XXXXX to opt-out.";
    campaign.ivr.optout_confirmed = "Your opt-out request has been registered.";
    
    // Linking our campaign to our addressbook
    campaign.addressbook.hash = addressbook.hash;
    
    // We want to get reports mailed
    campaign.options.send_report.enabled = true;
    campaign.options.send_report.emails = ["you@yourdomain.com"];
    
    // Lastly, we want to add some scheduling options
    // We want to pause the campaign each Monday and Thursday between 12:00 and 14:30.
    campaign.schedule.enabled = true;
    campaign.schedule.days = {
        'mon': [
            {
                'action' => 'pause', 'hour' => '12:00'
            },
            {
                'action' => 'unpause', 'hour' => '14:30'
            }
        ],
        'thu': [
            {
                'action' => 'pause', 'hour' => '12:00'
            },
            {
                'action' => 'unpause', 'hour' => '14:30'
            }
        ]
    };
    
    // Checking our campaign object for errors
    api.call('sendr/10/campaign.check', campaign).success(function (errors) {
        console.log(errors);
        // ...
    });
    
            

    Saving campaign

    Method

    Objects

    • Sendr.10.Campaign
    
    // Returns the full saved campaign object
    $fullCampaign = $api->call('sendr/10/campaign.save', [$campaign]);
    
    
    api.call('sendr/10/campaign.save', campaign);
    
            

    Testing our campaign


    We can test our campaign object against a given number to ensure that it behaves like intended.

    
    $number = '+33612345678';
    $result = $api->call('sendr/10/campaign.send_test_sms', [$number, $campaign, []]);
    
    
    var number = '+16469820800';
    api.call('sendr/10/campaign.send_test_sms', number, campaign, []);
    
            

    Start/pause/stop a campaign


    Starting our campaign as well as pausing or putting an end to it with a simple API call.

    
    $result = $api->call('sendr/10/campaign.start', [$campaign->hash]);
    $result = $api->call('sendr/10/campaign.pause', [$campaign->hash]);
    $result = $api->call('sendr/10/campaign.stop', [$campaign->hash]);
    
    
    api.call('sendr/10/campaign.start', campaign.hash);
    api.call('sendr/10/campaign.pause', campaign.hash);
    api.call('sendr/10/campaign.stop', campaign.hash);
    
            

    Getting campaign status

    
    $cpg = $api->call('sendr/10/campaign.get', [$campaign->hash]);
    var_dump($cpg->status);
    
    
    api.call('sendr/10/campaign.get', campaign.hash).success(function (cpg) {
        console.log(cpg.status);
    });
    
            

    Status objects look like the following JSON:

    
    {
          "run_id": 2,
          "state": "CREATED",
          "finished_cause": "NONE",
          "finished_cause_data": null,
          "percent": 0,
          "items_done": 0,
          "items_total": 1245,
          "items_total_t": 1245,
          "counters": {
            "cost": "0.00",
            "sent": 0,
            "billed": 0,
            "errors": 0,
            "answers": 0,
            "answers_unique": 0,
            "sent_status": {
              "RECEIVED": 0,
              "SENT": 0,
              "ERROR": 0,
              "FAILED": 0,
              "PENDING": 0,
              "REMOTE_QUEUED": 0,
              "EXPIRED": 0,
              "UNKNOWN": 0
            },
            "optouts": 0
          }
    
            

    Getting campaign report


    To get a report, the campaign must have ended or be stopped before, otherwise the report will not be available..

    Method

    Objects

    • Sendr.10.Report
    
    $report = $api->call('sendr/10/report.get', [$campaign->hash]);
    var_dump($report);
    
    
    api.call('sendr/10/report.get', campaign.hash).success(function (report) {
        console.log(report);
    });
    
            

    Export campaign report


    You have the possibility of generating a CSV file export of a campaign's report. A campaign may have several reports attached if it has been paused and started again.

    .

    Method

    Objects

    • Sendr.10.Report
    
    $webhook = new stdClass;
    $webhook->endpoint = 'http://yourdomain.com/endpoint';
    
    $report = $api->call('sendr/10/report.export_async', [$campaign->reports[0]->hash, 'CSV_UTF8', null, $webhook]);
    
    // ...
    // $exportData = POST data recieved on webhook endpoint when export is available
    $export = file_get_contents($exportData->result->url);
    
    
    var request = require('request');
    
    // partial webhook object to recieve status updates
    var webhook = {
        'endpoint': 'http://yourdomain.com/endpoint'
    };
    
    api.call('sendr/10/report.export_async', campaign.reports[0].hash, 'CSV_UTF8', null, webhook).success(function (response) {
        // ...
    });
    
    // var exportData = POST data recieved on webhook endpoint when export is available
    request.get(exportData.result.url, function (error, response, body) {
        if (!error && response.statusCode == 200) {
            var csv = body;
            // ...
        }
    });