(+234) 8187951071    
 support@xcall.com.ng 

Add Voice capabilities to your apps in minutes with our RESTful Voice API.
Focus on building your apps, we'll take care of the VOICE!

This documentation will provide instructions on how to quickly integrate our Voice messaging services into your application. Our Voice messaging API is a simple REST API and can interact with any HTTP client in any programming language You submit a POST HTTP request with a well-structured body and in response you get an id with which you can identify the broadcast. With that id you can poll for broadcast status and call log.

Getting Started

Step 1: Create an Xcall User Account.

In order to use our API, you will need an Xcall user account. The account you create will grant you access to our Customer Portal. If you already have an Xcall account you can skip this step. Otherwise, follow this link:

Create new account

Step 2: Generate an API Token:

Log in to your account and click on "API Access" on the left navigation menu.
  • Enter the name of your app to identify your credential.
  • Click on 'Genererate token' and confirm by clicking the 'Save' button.

Our API uses Basic HTTP Authentication. All API calls requires authentication, and the API expects for the auth to be included in a header that looks like the following:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Replace "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" with the API token you generated.

How To Create a Simple Voice Broadcast
How To Create an IVR Broadcast
How To Get Broadcast Statistics
How To Get Broadcast Call Records & IVR Responses

Creating a Simple Voice Broadcast

This API sends broadcast calls to multiple recipients and plays a voice message.

Request Parameters

API URL: https://xcall.com.ng/api/v1/createBroadcast

ParametersTypeDescription
broadcastName
(required)
stringA name that describes a broadcast
ttsMsg
stringText to be converted to speech and played to recipients.
ttsVoice
stringThe voice to use for test-to-speech synthesis. Any of 'uk-female', 'us-female', 'uk-male', 'us-male'. Default is 'uk-female'.
audioFileUrlstringInstead of text-to speech, you can specify URL of recorded file to be delivered as voice message to the recipients. The audio file must be uploaded online so its URL is available for file download. File must be MP3 format and file size must be less than 5MB.
to
(required)
arrayArray of recipients' phone numbers in E.164 format. (Example: "2348167891078")
from
(optional)
stringSender's phone number. This number appears on a recipient's phone when the call arrives. Only verified phone numbers are accepted.
startTime
(optional)
unix timestampdefines the unix timestamp to begin the broadcast. This prameter is required for scheduled broadcasts only , (broadcasts not to be sent immediately, but at scheduled time). Omit or leave blank to start broadcast immediately.

Response Parameters

ParametersTypeDescription
resultstringIndicates the result of an API request. The value is "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdintegerID that uniquely identifies the broadcast. With this ID you can poll for broadcast statistics, or call record.
msgLengthintegerDuration in seconds of the audio message to recipients
contactsTotalintegerNumber of contacts (or call destinations) for the broadcast
pendingCreditintegerThe quantity of credit units locked in to guarantee the broadcast. When the broadcast is completed, unused credit is returned to user's account.

Sample Code (PHP)

<?php

// Define a function that handles API requests.

function apiRequest($url$data){

        
$header = array('Authorization: Basic QWxhZjkyTpbjpvcGVuIHNlc2FtZQ==''Content-Type:application/json');  //Replace api token with your own.

    
$payloadjson_encode($data);   // convert $data to json 
    
$ch curl_init();
    
    
// Send authorization header with the AP token Without this, the query won't work
    
curl_setopt($chCURLOPT_HTTPHEADER$header);
    
    
curl_setopt($chCURLOPT_URL$url);
    
curl_setopt($chCURLOPT_RETURNTRANSFER1);
    
curl_setopt($chCURLOPT_POSTtrue);
    
curl_setopt($chCURLOPT_POSTFIELDS$payload);
    
    
$output curl_exec($ch);
    
$status curl_getinfo($chCURLINFO_HTTP_CODE);   // retrieve HTTP status code
    
curl_close($ch);

    
$response json_decode($outputtrue);      // convert json output to array object

    // Check status code for success.
    
if($status == 200){
        return 
$response;
    } 
    else { 
        die(
"Error: " $status);
    }
}


// Define broadcast name

$name"Test Broadcast";

// populate contacts array with phone numbers. Phone numbers must be in E.164 format.

$contacts= array();

$contacts[]= "2348187932xx";
$contacts[]= "234815678xxx";
$contacts[]= "234813456xxx";
$contacts[]= "234815676xxx";
$contacts[]= "234704234xxx";

// Define  sender's ID (optional)

$senderId"23481976933XX";

// Define text to convert to speech if you are  doing text-to-speech

$text"Hello. This is a test Voice broadcast.";

// Define voice to use to text-to-speech conversion. Default is 'uk-female';

$voice'uk-male';

// Define URL of audio recording (if you are using recorded audio instead)

$audioUrl'http://www.example.com/sounds/audio.mp3';


$broadcastData = array(
    
'broadcastName' => $name,
    
'ttsMsg' => $text,                // if you are doing text-to-speech
    
'ttsVoice' => $voice,
    
'audioFileUrl' => $audioUrl,      // URL of your MP3 audio file if you want to play recorded audio
    
'to' => $contacts,
    
'from' => $senderId,        // Only verified numbers accepted. Omit or leave blank ('') to use default.
    
'startTime' => ''    // Leave blank to start broadcast immediately.      
);


// Make API request

$resp apiRequest("https://xcall.com.ng/api/v1/simpleBroadcast"$broadcastData); 

// check if result is successful

if($resp['result'] == 'OK'){

    
// request is successful, show response parameters

    
var_dump($resp);

    
// Do whatever you want with the response parameters

    /*
    ...

    */
}
else{
    
// request failed. show reason.

    
echo $resp['msg'];
}

?>





How to Create an IVR Broadcast

Below are instructions and examples of how to create an ivr broadcast using our API.

Creating an ivr broadcast is in two steps:

  • Step 1: Create an IVR template. Once you have done this first step, you will have an ID for the template.
  • Step 2: Use the template to create an IVR broadcast.

Step 1: Creating an IVR Template

A Template is the major element of an IVR broadcast in our system. It defines the IVR flow.

To create a template, log into the Client Portal and navigate to 'IVR Templates > New Template'. Use the form that appears to define your call flow. You can add upto 10 questions (prompts). Each question can have upto 5 response choices (choice #1 to choice #5). Once created the ID of the template is displayed. You will need it in step 2 below.

A template can contain variables which are replaced with values when the template is rendered. Variables can hold any information such as URL, text for TTS, name of respondent, etc. Template variables begin and end with "%". For example, if you want to create a variable called "url", you'll use it in a template this way: %url%.

The table below explains the fields of the template form.

FieldExplanation
TypeYou can choose to do text-to-speech (TTS) for your ivr prompts or to use pre-recorded audio.
NameA name to identify a template.
TTS VoiceThe voice to use for test-to-speech synthesis. Any of 'uk-female', 'us-female', 'uk-male', 'us-male'.
Greeting/IntroThe text or URL of the message that first plays to respondents to introduce you or your organisation
Question textThe text of a question
Question audioThe URL of question recording.
Choice #1 - Choice #5Text of response options corresponding to dtmf 1 to dtmf 5.

Step 2: Create Broadcast using the IVR Template from Step 1

You can create IVR broadcasts in your own app using the template ID from step 1 above.

Request Parameters

API URL : https://xcall.com.ng/api/v1/ivrBroadcast

ParametersTypeDescription
name (required)stringA name for the broadcast
templateId (required)integerThe ID of the ivr template to use.
to (required)arrayDestination phone numbers in E.164 format
fromstringSender's phone number in E.164 format. Only verified numbers are accepted. Omit or leave blank ("") to use defaut.
maxCallLengthinteger Maximum duration of each call in seconds. The system will terminate a call when this time elapes. Allow sufficient time for the call flow to finish. Default is 120 seconds.
templateDataarrayAssociative array of values for variables in the template. The array keys must match the variable names in the template. For example, if the template contains a variable "%url%", templateData must contain an array key of same name "url" and its assigned value.
startTimeUnix TimestampTime to begin the broadcast in unix timestamp format. Leave blank ("") or omit to start broadcast immediately.

Response Parameters

ParametersTypeDescription
resultstringIndicates result of the request. "OK" if successful, "ERROR" if not successful.
msgstringA description of the result.
idintegerAn ID that uniquely identifies the broadcast.
templateIdstringThe ID of the IVR template used
dstCountstringTotal number of call destinations (recipients).
startTimeunix timestampThe time to begin the broadcast in unix timestamp format.
pendingCreditfloatThe credit locked in to guarantee the broadcast. When the broadcast is completed, unused credit is returned to user's account

<?php

/*  Define function to handles API requests.  */

function apiRequest($url$data){
    
    
// This function makes API requests.
    
    // Set your API token here
        
$header = array('Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==''Content-Type:application/json');  

    
$payloadjson_encode($data);   // convert $data to json 
    
$ch curl_init();
    
    
// Send authorization header with the AP token Without this, the query won't work
    
curl_setopt($chCURLOPT_HTTPHEADER$header);
    
    
curl_setopt($chCURLOPT_URL$url);
    
curl_setopt($chCURLOPT_RETURNTRANSFER1);
    
curl_setopt($chCURLOPT_POSTtrue);
    
curl_setopt($chCURLOPT_POSTFIELDS$payload);
    
    
$output curl_exec($ch);
    
$status curl_getinfo($chCURLINFO_HTTP_CODE);   // retrieve HTTP status code
    
curl_close($ch);

    
$response json_decode($outputtrue);      // convert json output to array object

    // Check status code for success.
    
if($status == 200){
        return 
$response;
    } 
    else { 
        die(
"Error: " $status);
    }
}
        
    
$templateId345;  // Change this to your template ID.


// populate destination array with your  contacts. Phone numbers must be in E.164 format.

$to= array();
$to[]= "2348187932xx";
$to[]= "234815678xxx";
$to[]= "234813456xxx";
$to[]= "234815676xxx";
$to[]= "234704234xxx";

$data = array(
        
'name' => 'Sample IVR broadcast',
        
'templateId' => $templateId,    // Define the ivr template to use for the broadcast 
        
'to' => $to,            // Array of recipients phone numbers
    
'from' => '',            // Sender's phone number in E.164 format. Only verified numbers are accepted. Omit or leave blank ("") to use default.
    
'maxCallLength'=>'60',        //  Maximum duration of each call in seconds . Default is 120 seconds.
    
'startTime'=> ''        // Time to begin broadcast in unix timestamp format. Omit or leave blank ("") to start broadcast immediately.
);

$resp apiRequest("https://xcall.com.ng/api/v1/ivrBroadcast"$broadcastData);     // create the broadcast

if($resp['result'] == 'OK'){

    
// requeest is successful, show response parameters

    
var_dump($resp);
}
else{
    
// request failed. show reason.

    
echo $resp['msg'];
}

?>




How To Get Broadcast Statistics

This API provides statistics such as number of sent calls, number of answered calls, contacts remaining, etc.

Request Parameters

API URL: https://xcall.com.ng/api/v1/broadcastStats

ParametersTypeDescription
broadcastId
(required)
integerThe ID that uniquely identifies a broadcast

Response Parameters

ParametersTypeDescription
resultstringIndicates result of API request. "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdintegerReturns the ID of the broadcast.
broadcastNamestringThe Name of the broadcast.
fromintegerThe sender ID
statusstring

The current status of the broadcast.

finished:  Broadcast is completed
running:  Broadcast is in progress
waiting:   Broadcast is waiting for scheduled start time
paused:  Broadcast is paused
cancelled:  Broadcast is cancelled
contactsTotalintegerThe total number of contacts for the broadcast.
dialedContactsintegerThe number of contacts dialed.
answeredCallsintegerThe number of answered calls.
contactsRemainingintegerThe number of calls/contacts remaining.
startTimeunix timestampThe time the broadcast started in unix timestamp format.
endTimeunix timestampThe time the broadcast finished in unix timestamp format.
maxCallLengthintergerThe maximum dumration (in seconds) of a call in the broadcast.
pendingCreditfloatThe amount of credit set aside to guarantee the broadcast. When the broadcast is completed, unused credit is returned to user's account.
billedCreditfloatThe actual cost of the broadcast campaign.

Sample Code (PHP)

<?php
$api_url
"https://xcall.com.ng/api/v1/stats";

// Define broadcast parameters

$idXXXX;  // Specify the id of the broadcast.
$data = array('broadcastId' => $id);

$header = array('Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==');  // Set your API token here

$ch curl_init();
curl_setopt($chCURLOPT_HTTPHEADER$header);
curl_setopt($chCURLOPT_URL$api_url);
curl_setopt($chCURLOPT_RETURNTRANSFER1);
curl_setopt($chCURLOPT_POSTtrue);
curl_setopt($chCURLOPT_POSTFIELDS$data);
$output curl_exec($ch);
$httpCode curl_getinfo($chCURLINFO_HTTP_CODE);   // store HTTP status code
curl_close($ch);

$responsejson_decode($outputtrue);  // decode JSON response

// If successful, HTTP status code will be 200 and result OK
if($httpCode == 200 && trim($response['result'])=='OK'){

       
// Extract reponse values
    
    
echo $response['broadcastId'];
    echo 
$response['broadcastName'];
    echo 
$response['status'];
    echo 
$response['totalCount'];
    echo 
$response['dialedCalls'];
    echo 
$response['answeredCalls'];
    echo 
$response['callsRemaining'];
    echo 
$response['startTime'];
    echo 
$response['endTime'];
}
else{
        
// if request failed, show reason
        
echo $response['msg'];
        echo 
$httpCode;
}

?>



How To get Broadcast Call Records & IVR Response

This API resource enables you to get call logs for sent voice messages. For IVR broadcasts it also provides DTMF responses to IVR questions.

Request Parameters

API URL: https://xcall.com.ng/api/v1/broadcastLog

ParametersTypeDescription
broadcastId (required)integerThe ID of a broadcast
limit integerMaximum number of call records to return. Default value is 25. Must not be greater than 50.
offsetintegerOffset to the start of a given page. The default is 0.

Response Parameters

ParametersTypeDescription
resultstringIndicates result of API request. "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdintegerReturns the ID of the broadcast.
tostringThe destination phone number
fromstringThe sender's phone number
statusstringIndicates whether contact has been dialed or pending
resultstringIndicates whether call was answered or failed.
dialedTimeunix timestampThe unix timestamp when the call was first attempted.
limitintegerA maximum number of returned records. If totalCount < limit, assume no more records.
offsetintegerreturns the offset to the start of a the record. This parameter is useful for pagination.
ivrResponse array provides the dtmf response to each question of an IVR broadcast.

Sample Code (PHP)

<?php
$api_url
"https://xcall.com.ng/api/v1/logs";

// Define broadcast parameters

$idXXXX;  // Specify the id of the broadcast.
$offset 0;
$limit 25;
$data = array(
        
'broadcastId' => $id,
        
'offset' => $offset,
        
'limit' => $limit
);

$header = array('Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==');  // Set your API token here

$ch curl_init();
curl_setopt($chCURLOPT_HTTPHEADER$header);
curl_setopt($chCURLOPT_URL$api_url);
curl_setopt($chCURLOPT_RETURNTRANSFER1);
curl_setopt($chCURLOPT_POSTtrue);
curl_setopt($chCURLOPT_POSTFIELDS$data);
$output curl_exec($ch);
$httpCode curl_getinfo($chCURLINFO_HTTP_CODE);   // store HTTP status code
curl_close($ch);

$responsejson_decode($outputtrue);  // decode JSON response

// If successful, HTTP status code will be 200 and result OK
if($httpCode == 200 && trim($response['result'])=='OK'){

    echo 
$response['broadcastId']. "\n";
    echo 
$response['broadcastName'] . "\n";
    echo 
$response['status'] . "\n";
    echo 
$response['recordCount'] . "\n";
    echo 
$response['limit'] . "\n";
    echo 
$response['offset'] . "\n";


       
// Extract call logs
    
    
$logs $response['logs'];
    foreach(
$logs as $row){
        echo 
$row['phoneNum']. " " $row['dialedTime'] . " " $row['callResult'] . "\n";  
    }    
}
else{
        
// if request failed, show reason
        
echo $response['msg'];
        echo 
$httpCode;
}
?>








Copyright © 2018  xcall.com.ng     All rights reserved