VOICE BROADCAST

API (Single DTMF)

User Guide

Date: 09/04/2018 Version no.: 1.0

1|Page VOICE BROADCAST API

 Table of Contents

PRODUCT DESCRIPTION ........................................................................................ 3

The Concept .......................................................................................................................................... 3

API GUIDE ................................................................................................................. 3

Template API ......................................................................................................................................... 3

Request Base URL ............................................................................................................................. 3
Required Parameters .......................................................................................................................... 3
Required WAV Files ............................................................................................................................ 4
Template Description .......................................................................................................................... 4
Response ............................................................................................................................................ 4

Broadcast API ........................................................................................................................................ 6

Request Base URL ............................................................................................................................. 6
Required Parameters .......................................................................................................................... 6
Required File to be Uploaded ............................................................................................................. 6
Response ............................................................................................................................................ 7

Example.................................................................................................................................................. 8
Scenario .............................................................................................................................................. 8

CALLBACK API ...................................................................................................... 11

WORKFLOW ........................................................................................................... 11

Voice System Workflow ...................................................................................................................... 12

2|Page VOICE BROADCAST API

PRODUCT DESCRIPTION
The Concept
The document explains the steps required to make bulk voice calls through HTTP API. In order
to make a successful voice call the user has to go through a two-step process. First step would
be to make a URL request to a template API along with required wav files to set the campaign in
a ready state and the next step would be to invoke the Delivery API along with the recipient file to
execute the campaign.

API GUIDE
The document explains the steps required to make bulk voice calls through HTTP API. In order
to make a successful voice call the user has to go through a two-step process. First step would
be to make a URL request to a template API along with required wav files to set the campaign in
a ready state and the next step would be to invoke the Broadcast API along with the recipient file
to execute the campaign.

Template API

Request Base URL

http://IP/voiceapi/tapi.php?account=<account>&pin=<pin>&templateid=<templateid>&retry=<ret
ry>

Based on the template, one or more additional wav files has to be uploaded along with the above
parameters as multipart-form data via HTTP POST.

Required Parameters

Parameter Description
Account* Represents the account name, which will be provided by Karix
Pin* Represents the password, which will be provided by Karix
Templateid* Unique number which represents the actual call flow

3|Page Voice Broadcast API

 Retry Number of Retry If Call Fails (Maximum is 3 and default is 0)

Required WAV Files

File Name Description

VC<integer> All the wav/mp3 files to be passed via HTTP POST as per the clip count
of the template. The integer values should start by 1 and incremented
thereafter. For example for a template with three clip count, the files
parameter should be VC1, VC2 and VC3.

Template Description

API supports 6 pre-defined templates, additional template can be supported based on customized
requirement. Below are the template details:

Name Description Template ID Voice Clip

Count
OneClip_IVR Single Clip Playback 3 1

Note: For any additional requirement customer needs to requests Karix team in advance.

Response

The response is a JSON format.

On a successful request the response would be

4|Page Voice Broadcast API

 {
"campaignid": <unique id>
"code": 100
"ts": "yyyy-mm-dd HH24:mi:ss"
"status": "success"
"templateid": <id from the request param>"
}

On error the response would be

{
"status": "failure"
"code": <one of the possible values as shown below>
"desc": "< brief description of the error >"
"ts": "yyyy-mm-dd HH24:mi:ss"
"templateid": <id from the request param>"
}

Parameter Description
campaignid System generated unique id for the request. This will be used in the
broadcast API to send voice calls.

code Represents the status code for the request.

100 (Success)
101 (Invalid Parameters)
102 (Authentication Failed)
103 (Account Expired)
104 (Account Locked)
105 (Invalid Templateid)
500 (System Failure)

5|Page Voice Broadcast API

 Parameter Description
ts Represents the Received timestamp in yyyy-mm-dd H24:mi:ss
format
status Represents the status of the request. Possible values would be
success/failure
templateid Represents the templateid that came with the request

Broadcast API
Request Base URL

http://IP/voiceapi/bapi.php?account=acc&pin=123&campaignid=

Apart from the above parameters the system expects a file to be uploaded as multipart-form data
via HTTP POST. The file being uploaded should hold the recipients number. There is no filename
convention. Only .txt file is supported as of now.

The uploaded file should contain only the recipient number. Each number should be on its own
line. The recipient number can be represented as +14158675309 or 14158675309

Required Parameters

Parameter Description
account Represents the account name, which will be provided by Karix
pin Represents the password, which will be provided by Karix
campaignid Represents the response param "campaignid" from Template API

Required File to be Uploaded

POST parameter for the csv file: contactsFile

File Name Description

6|Page Voice Broadcast API

 <filename>.csv Represents the recipient list, where each recipient is separated by
new line char

Response

The response is a JSON format.

On a successful request the response would be

{
"campaignid": <id obtained from Template API>
"code": 100
"ts": "yyyy-mm-dd HH24:mi:ss"
"status": "success"
}

On error the response would be

{
"status": "failure"
"code": <one of the possible values as shown below>
"desc": "< brief description of the error >"
"ts": "yyyy-mm-dd HH24:mi:ss"
"campaignid": <id from the request param>"
}

Parameter Description
campaignid Represents the ID obtained through Template API.
code Represents the status code for the request.
100 (Success)
101 (Invalid Parameters)
102 (Authentication Failed)

7|Page Voice Broadcast API

 Parameter Description
103 (Account Expired)
104 (Account Locked)
105 (Invalid Templateid)
500 (System Failure)

ts Represents the Received timestamp in yyyy-mm-dd H24:mi:ss

format
status Represents the status of the request. Possible values would be
success/failure

Example
Let us assume the customer has been provided with templateid 3 and 6 respectively. These
templateid refers to a pre-defined call flow.

Scenario

Template to be used is 3, which is configured to accept only one clip. The idea of this template is
to play the clip when the user answers the call.

First step is to configure a campaign with this templateid by requesting the Template API

http://IP/voiceapi/tapi.php?account=acc&pin=123&templateid=3

Along with the necessary file upload, in this case the file abc.mp3. Please note the filename POST
parameter should be VC1.

For example the following php code could generate the request successfully:

$acc = <username as provided by Karix>

$pin = <password as provided by Karix>
$templateid = 3;
$retry = 2;

8|Page Voice Broadcast API

$url = "IP/voiceapi/tapi.php?account=$acc&pin=$pin&templateid=$templateid&retry=$retry";
$audiodata = "D:\\Clips\\abc.mp3";
$postfields = Array( "VC1" => "@$audiodata" );
$campaign_id = call_url($url, $postfields);
echo $campaign_id;

function call_url($url, $postfields) {

$headers = array("Content-Type:multipart/form-data");
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
$result = curl_exec($ch);
curl_close($ch);
return $result;
}

On Successful request to the above URL, the response would be

{
"campaignid": 1100
"code": 100
"ts": "2014-03-27 16:40:10"
"status": "success"
"templateid": 3
}

9|Page Voice Broadcast API

Now the campaign is configured and ready for making voice calls. You can create any number of
campaigns with the same templateid, yet providing the option to configure file with different
content.

The next step would be to make the calls by requesting the Broadcast API

http://IP/voiceapi/bapi.php?account=acc&pin=123&campaignid=1100

along with the recipient list file. Please note that the campaignid used is the value you got from
Template API. If you have configured multiple campaigns out of the same templateid please make
sure you use the appropriate campaignid.

For example the following php code could generate the request successfully:

$acc = <username as provided by Karix>

$pin = <password as provided by Karix>
$campaignid = 1100;
$url = "IP/voiceapi/bapi.php?account=$acc&pin=$pin&campaignid=$campaignid ";
$csvdata = "D:\\Numbers\\abc.csv";
$postfields = Array("contactsFile" => "@$csvdata");

$server_response = call_url($url, $postfields);

echo $server_response;

function call_url($url, $postfields) {

$headers = array("Content-Type:multipart/form-data");
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

10 | P a g e Voice Broadcast API

 curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
$result = curl_exec($ch);
curl_close($ch);
return $result;
}

The targeted recipients would receive voice calls on successful API call.

CALLBACK API
In order to provide each and every call details to 3rd party system, CallBack API can be integrated
with Karix system. CallBack API will be called after every number is processed from Karix voice
system.

Call status would typically include information like:

• User was reachable or not. In case not reachable what was the reason
• User picked the call or not
• In case user picked the call what was the duration of call

API:
https://local.xyz.com/voice_Karix/

Parameters:
camp_id: Call was related to which campaign
destination: Number which was called
pickup_time: Call pick up time
hangup_time: Call hang up time
reason: Call dial status
duration: Call duration

WORKFLOW

11 | P a g e Voice Broadcast API

Voice System Workflow
• In order to begin with voice broadcast, 3rd party system will send the request to Karix
system through Template API.
• On receiving the request through Template API, Karix voice system will check if necessary
template and voice clips (.wav / .mp3 format) are available to execute the campaign.
• Depending on necessary check Karix system will send response code to 3rd party system
• Response code “success” i.e. 100 means Karix voice system is ready to execute the voice
campaign
• In order to start the campaign customer needs to send request through Broadcast API
with all required parameters and target base file in .csv format
• On receiving the Broadcast API request Karix voice system initiates the voice call to target
base uploaded.
• Re-try parameters will be passed through Template API

12 | P a g e Voice Broadcast API