Methods

Objects

SENDR Voice broadcasting Campaigns

Use the power of the SENDR API to create and manage your voice 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 broadcasting messages to your clients now.

In these examples, we will focus on creating voice broadcasting campaigns without user interaction.

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 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.

    Methods

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

    Method

    
$campaign = $api->call('sendr/10/campaign.get_object_template', ['VOICE_SIMPLE']);


api.call('sendr/10/campaign.get_object_template', 'VOICE_SIMPLE').success(function (campaign) {
    // ...
});

    You will receive a partial campaign object like the following:

    
{
    "type": "VOICE_SIMPLE",
    "name": "",
    "options": {
      "cli": "BLOCKED",
      "ccl": 1,
      "call_recording": false,
      "auto_stop": {
        "enabled": false,
        "per_answer_count": {
          "enabled": false,
          "count": 0
        },
        "per_key": {
          "enabled": false,
          "key_0": 0,
          "key_1": 0,
          "key_2": 0,
          "key_3": 0,
          "key_4": 0,
          "key_5": 0,
          "key_6": 0,
          "key_7": 0,
          "key_8": 0,
          "key_9": 0
        }
      },
      "followup": {
        "enabled": false,
        "conditions": {
          "no_response": false,
          "voicemail_detected": false,
          "short_call": false,
          "short_call_duration": 5
        },
        "actions": {
          "callback": {
            "enabled": false,
            "count": 1,
            "delay_minutes": 30
          },
          "sms": {
            "enabled": false,
            "sender": "",
            "text": ""
          }
        }
      },
      "optout_enabled": false,
      "optout_blacklist": "",
      "nature": "MARKETING",
      "send_report": {
        "enabled": false,
        "emails": [],
        "phones": []
      }
    },
    "ivr": {
      "prompt": [],
      "goodbye": [],
      "voicemail_detect_method": "NO",
      "voicemail_detect_media": [],
      "voicemail_broadcast": [],
      "broadcast": [],
      "optout_intro": [],
      "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
    • Media.Library

    Method

    
// $campaign = partial object from last step
// $addressbook = addressbook object created in first step

// Setting a name
$campaign->name = "My CALLR Campaign";

// Linking our campaign to our addressbook
$campaign->addressbook->hash = $addressbook->hash;

// Setting voicemail detection to AUTO
$campaign->ivr->voicemail_detect_method = "AUTO";

// Setting main messages to be played, can be multiple files.
// Number are IDs of Media.library objects
$campaign->ivr->broadcast = [133872, 133876];

// Setting CLI to a number we own
$campaign->options->cli = "+33612345678";

// Max concurrent calls
$campaign->options->ccl = 5;

// Recording calls
$campaign->options->call_recording = true;

// We want an automatic callback 2 times if voicemail is detected or if no answer
$campaign->followup->enabled = true;
$campaign->followup->conditions->voicemail_detected = true;
$campaign->followup->conditions->no_response = true;
$campaign->followup->actions->callback->enabled = true;
$campaign->followup->actions->callback->count = 2;

// If still no answer, we want to send an SMS
$campaign->followup->sms->enabled = true;
$campaign->followup->sms->sender = "SMS";
$campaign->followup->sms->text = "We tried to reach you!";

// 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";

// Linking our campaign to our addressbook
campaign.addressbook.hash = addressbook.hash;

// Setting voicemail detection to AUTO
campaign.ivr.voicemail_detect_method = "AUTO";

// Setting main messages to be played, can be multiple files.
// Number are IDs of Media.library objects
campaign.ivr.broadcast = [133872, 133876];

// Setting CLI to a number we own
campaign.options.cli = "+447890123456";

// Max concurrent calls
campaign.options.ccl = 5;

// Recording calls
campaign.options.call_recording = true;

// We want an automatic callback 2 times if voicemail is detected or if no answer
campaign.followup.enabled = true;
campaign.followup.conditions.voicemail_detected = true;
campaign.followup.conditions.no_response = true;
campaign.followup.actions.callback.enabled = true;
campaign.followup.actions.callback.count = 2;

// If still no answer, we want to send an SMS
campaign.followup.sms.enabled = true;
campaign.followup.sms.sender = "SMS";
campaign.followup.sms->text = "We tried to reach you!";

// 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.

    Method

    Object

    • Sendr.10.Campaign.TestCall
    
$number = '+33612345678';
$result = $api->call('sendr/10/campaign.start_test_call', [$number, $campaign, []]);


var number = '+33612345678';
api.call('sendr/10/campaign.start_test_call', 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.

    Methods

    
$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

    Method

    
$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": 1,
      "state": "FINISHED",
      "finished_cause": "DONE",
      "finished_cause_data": null,
      "percent": 100,
      "items_done": 12,
      "items_total": 12,
      "items_total_t": 12,
      "counters": {
        "broadcast": {
          "completed": 7,
          "history": {
            "2016-02-29 13:00:00": 7
          }
        },
        "cost": "1400",
        "call_status": {
          "ANSWERED/COMPLETE": 7,
          "ANSWERED/INCOMPLETE": 0,
          "ABSENT/NO_ANSWER": 0,
          "ABSENT/BUSY": 0,
          "ABSENT/VOICEMAIL_DETECTED": 0,
          "ERROR/UNALLOCATED_NUMBER": 0,
          "ERROR/REJECTED": 2,
          "ERROR/BLACKLISTED": 3,
          "ERROR/OTHER": 0
        },
        "calls": 12,
        "calls_active": 0,
        "calls_answered": 7,
        "acd": 7,
        "retries": {
          "count": 0,
          "sms_sent": 0,
          "cause": {
            "NO_RESPONSE": 0,
            "VOICEMAIL_DETECTED": 0,
            "SHORTCALL": 0,
            "CALLBACK": 0
          }
        },
        "optouts": 0,
        "keys": {
          "key_0": 0,
          "key_1": 0,
          "key_2": 0,
          "key_3": 0,
          "key_4": 0,
          "key_5": 0,
          "key_6": 0,
          "key_7": 0,
          "key_8": 0,
          "key_9": 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 CSV file exports of campaign's reports. 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;
        // ...
    }
});