Methods
Objects
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
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")
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. }); });
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
}
Let's edit our partial object to fit our needs and check the assigned values for errors.
// $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); // ... });
// Returns the full saved campaign object $fullCampaign = $api->call('sendr/10/campaign.save', [$campaign]);
api.call('sendr/10/campaign.save', campaign);
We can test our campaign object against a given number to ensure that it behaves like intended.
$number = '+16469820800'; $result = $api->call('sendr/10/campaign.send_test_sms', [$number, $campaign, []]);
var number = '+447890123456'; api.call('sendr/10/campaign.send_test_sms', number, 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);
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": 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
}
To get a report, the campaign must have ended or be stopped before, otherwise the report will not be available..
$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); });
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.
.$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; // ... } });