Introduction
The Xcall API is built from the ground up as a REST API and can interact with any HTTP client in any programming language. This documentation provides instructions on how to quickly integrate our voice services into your application. It is easy to understand and provides code samples to point you in the right direction.
Get Authenticated
Our API uses HTTP Basic Authentication over an encrypted communication channel to verify users. All API requests require authentication using valid API credentials.You can obtain XCall API credentials form our web platform in 2 quick steps:
Step 1. Visit https://xcall.com.ng to create a user account. If you already have an Xcall user account, you can skip this step.
Step 2: Login using the user account from step 1.
- Navigate to Settings --> API Credentials
- Enter your App name to identify your credential, and click on "Generate".
- Click on "Save" to confirm and save the credentials.
Request Headers
These are the standard request headers that are needed when authenticating with the API. The API endpoints accepts json content types for requests and will produce a json response. You shoud specify "Content-Type: application/json" and "Accept: application/json" in the header section of API requests.
Parameter | Type | Description |
---|---|---|
Authorization (Required) | string | Must include the word "Basic" followed by the auth token you generated. Should look like this:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
|
content-Type (Required) | string | The requests content type. Must be application/json |
Accept (Required) | array_string | The requests response type. Must be application/json |
Voice Messaging
Creating Outbound Calls
Path: https://api.xcall.com.ng/v3/callThis API endpoint sends automated calls to one or multiple phone numbers and plays a recorded audio message or text-to-speech message.
Request Parameters
Parameter | Type | Description |
---|---|---|
broadcastName (optional) | string | A name or title that describes the broadcast. |
from (optional) | string | Sender ID. This number will show on recipients' phone numbers when the call arrives. Only verified phone numbers in international format are accepted. |
to (required) | array_string | Array of destination (recipients') phone numbers. Phone numbers must be in international format. (Example: "2347031234567") |
ttsMsg | string | Text-to-Speech message. This is the text that will be converted to speech. Adding a pause between words is possible by using the comma character β,β. For example, if you want to have a 2 second pause after each word, then the text parameter should look like this βone,,, two,,,, three,,,,β. Each comma creates a pause of 0.5 seconds. |
ttsVoice | string | Defines the voice in which text would be synthesized. Options are 'uk-female', 'us-female', 'uk-male', 'us-male'. |
speechRate | double (1) | Defines the speed of speech in the resulting message. Effective only when using text-to-speech. Supported range is from 0.50 (slow speech) to 2.00 (fast speech). Default is 0.85. |
audioFileUrl | string | You can specify a URL of an audio recording to play to the call recipients instead of text-to-speech. The audio file must be in .mp3 format and must be downloadable from the URL specified. The File size must not exceed 5MB. |
startTime (optional) | unix timestamp | Unix timestamp that specifies the time to begin the calls. If startTime is not set, the calls will begin immediately. |
notifyUrl | string | The URL on your callback server to which the Delivery report will be sent. |
Request Example
POST /v3/call HTTP/1.1
Host: https://api.xcall.com.ng
Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==
Content-Type: application/json
Accept: application/json
{
"from":"234703XXXXXXX",
"to":[
"234810XXXXXXX",
"234803XXXXXXX"
],
"ttsMsg": "Hello Jane! This call is from ABC Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid ID. Thank you.",
"ttsVoice": "uk-male"
}
curl -X POST \
-H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"from":"234703XXXXXXX",
"to":[
"234810XXXXXXX",
"234803XXXXXXX"
],
"ttsMsg": "Hello Jane! This call is from ABC Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid ID. Thank you.",
"ttsVoice": "uk-male"
}' "https://api.xcall.com.ng/v3/call"
<?php
/* Define sender ID
$from= "234703XXXXXXX";
/* populate destination array. */
$to = [];
$to[]= "234810XXXXXXX";
$to[]= "234803XXXXXXX";
/* If message is text to speech, define its parameters */
$ttsMsg= "Hello Jane! This call is from ABC Logistics. We want to notify you that you have a parcel to pickup at our office. Please come with a valid ID. Thank you.";
$ttsVoice= "uk-male";
/*if message is recorded audio, define its URL */
$audioFileUrl= "http://www.example.com/sounds/audio.mp3";
$requestData = array(
"broadcastName" => $name,
"ttsMsg" => $ttsMsg,
"ttsVoice" => $ttsVoice,
"audioFileUrl" => $audioFileUrl,
"to" => $to,
"from" => $from,
"startTime" => "567889900" /* Unix timestamp to begin the calls. Defaut is to begin calls immediately. */
);
/* convert requestData to json format */
$requestData = json_encode($requestData);
/* Make API request */
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.xcall.com.ng/v3/call",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $requestData,
CURLOPT_HTTPHEADER => array(
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json",
"accept: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response Parameters
Parameter | Type | Description |
---|---|---|
result | string | Indicates the result of an API request. The value is "OK" if successful and "ERROR" if unsuccessful. |
msg | string | A description of the result. |
broadcastId | string | ID that uniquely identifies the broadcast request. You can use this ID to retrieve delivery report and call log. |
msgLength | int | Duration (in seconds) of voice message |
dstCount | int | Number of call recipients or destination phone numbers. |
reservedCredit | int | The credit units reserved for the calls. When the request is completed, unused credit is returned to user's account. |
Creating Outbound IVR Calls
Path: https://api.xcall.com.ng/v3/ivrThis API endpoint makes outbound interactive voice calls to one or multiple phone numbers. You can send automated phone calls to multiple recipients, ask questions, and record responses in real time.
Creating an IVR broadcast is in two steps:
- Step 1: You create an IVR template.
- Step 2: You create outbound calls using the template from step 1.
Step 1: Creating an IVR Template
An IVR Template is the major element of an IVR broadcast in our system. It defines the call flow logic for an IVR call.
To create an IVR template, logon to the client web portal. Navigate to Settings → IVR Templates → New IVR Template and follow the instructions on the page. Note the ID of the template you have created. You can use a single template for multiple IVR broadcasts.
Step 2: Create broadcast using template from step 1
Simply make an api request using the template ID from step 1 above. The request parameters are described below.
Request Parameters
Parameter | Type | Description |
---|---|---|
broadcastName | string | A name or title that describes the broadcast. |
templateId (required) | string | ID of the IVR template that defines an outbound IVR call/broadcast. |
to (required) | array-string | Array of destination (recipients') phone numbers. Phone numbers must be in international format. (Example: "2347031234567") |
from | string | Sender ID. This number will show on recipients' phone numbers when the call arrives. Only verified phone numbers are accepted. |
maxCallLength | int | Maximum permissible duration of IVR call in seconds. The system will terminate the call when this time elapes. Default is 120 seconds. |
customData | array_string | Array of values that corresponds to custom variables in IVR template. Array keys must match the variable names in IVR template. |
startTime | Unix timestamp | Unix timestamp that specifies the time to begin the calls. If startTime is not set, the calls will begin immediately. |
notifyUrl | string | The URL on your your server to which Delivery report will be sent. |
maxRetries | int | The maximum number of retry attempts. Limit is 2. |
waitTime | int | The time (in minutes) to wait before retry. |
Request Example
POST /v3/ivr HTTP/1.1
Host: https:api.xcall.com.ng
Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==
Content-Type: application/json
Accept: application/json
{
"templateId": "123DG2345D7BB178",
"from":"2349081235467",
"messages":[
{
"to":"2347031234567",
"customData":{
"name": "John",
"appointment": "September 12, 2019"
}
},
{
"to":"2348151234568",
"customData":{
"name": "Mary",
"appointment": "September 10, 2019"
}
},
],
"startTime": "56789467820",
"maxRetries": "3",
"waitTime": "5",
"notifyUrl": "https://www.mydomain.com/voice/process_callbacks"
}
curl -X POST \
-H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"templateId": "123DG2345D7BB178",
"from":"2349081235467",
"messages":[
{
"to":"2347031234567",
"customData":{
"name": "John",
"appointment": "September 12, 2019"
}
},
{
"to":"2348151234568",
"customData":{
"name": "Mary",
"appointment": "September 10, 2019"
}
},
],
"startTime": "56789467820",
"maxRetries":"3",
"waitTime": "5",
"notifyUrl": "https://www.mydomain.com/voice/process_callbacks"
}' "https://api.xcall.com.ng/ivr"
<?php
/* Define sender ID
$from= "2348191234567";
$templateId= "1475";
/* populate messages. */
$messages = [];
$messages[]= array(
"to"=> 2347031234567",
"customData"=> array(
"name": "John",
"appointment": "September 11"
);
$messages[]= array(
"to"=> 2348151234568",
"customData"=> array(
"name": "Mary",
"appointment": "September 14
);
$requestData = array(
"broadcastName" => $name,
"from" => $from
"templateId" => $templateId,
"messages" => $messages
"startTime" => "56789467820",
"maxRetries" => "3",
waitTime" => "5",
"notifyUrl" => "https://www.mydomain.com/voice/process_callbacks"
);
/* convert requestData to json format */
$requestData = json_encode($requestData);
/* Make API request */
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.xcall.com.ng/api/ivr",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $requestData,
CURLOPT_HTTPHEADER => array(
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json",
"accept: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response Parameters
Parameter | Type | Description |
---|---|---|
result | string | Indicates the result of an API request. The value is "OK" if successful and "ERROR" if unsuccessful. |
msg | string | A description of the result. |
broadcastId | int | ID that uniquely identifies the request. With this ID you can retrieve the status and call records. |
msgLength | int | Duration (in seconds) of voice message |
dstCount | int | Number of call recipients or destination phone numbers. |
reservedCredit | int | The credit units reserved for the calls. When the request is completed, unused credit is returned to user's account. |
Getting Delivery Reports
Path: https://api.xcall.com.ng/v3/callReportThis API resource enables you to get call logs for sent voice calls and outbound IVR. For IVR calls it also provides recipients' dtmf responses.
Request Parameters
Parameters | Type | Description |
---|---|---|
broadcastId (required) | int | The ID which uniquely identifies the broadcast. |
limit | int | Maximum number of records to return. Default value is 50. |
offset | int | Offset to the start of the record. Useful for pagination. Default is 0. |
Request Example
POST /v3/callReport
Host: https://api.xcall.com.ng
Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==
Content-Type: application/json
Accept: application/json
{
"broadcastId":"5128",
"limit":"25",
"offset":"0"
}
curl -X POST \
-H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"broadcastId":"5128",
"limit":"25",
"offset":"0"
}' "https://api.xcall.com.ng/v3/callReport"
<?php
/* Define broadcast ID
$broadcastId= "5128";
$requestData = array(
"broadcastId" => $roadcastId,
"limit" => "25",
"offset" => "0"
);
/* convert requestData to json format */
$requestData = json_encode($requestData);
/* Make API request */
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.xcall.com.ng/v3/callReport",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $requestData,
CURLOPT_HTTPHEADER => array(
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json",
"accept: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response Parameters
Parameters | Type | Description |
---|---|---|
result | string | Indicates result of API request. "OK" if successful. |
broadcastId | int | Returns the ID of the broadcast. |
broadcastName | int | Returns the name of the broadcast. |
from | string | The sender ID |
status | string | The current status of the broadcast. Possible values are:
|
dstCount | string | The total number of destination phone numbers (recipients). |
dialedCount | string | The number of destination numbers processed. |
answeredCalls | string | The number of calls answered. |
remainingCalls | string | The number of destination numbers remaining. |
startTime | string | The time (in unix timestamp) that the broadcast started. |
endTime | string | The time (in unix timestamp) that the broadcast completed. |
maxCallLength | string | The maximum call duration in seconds. |
billedCredit | string | The cost of the broadcast. |
offSet | int | Offset to the start of the record. |
limit | int | Maximum number of records to return. |
callRecord | array | contains call records |
dialedTime | int | The unix timestamp when call was first attempted. |
callResult | string | Indicates whether call was answered or not. |
ivrResponse | array | contains the response to IVR questions. |
SMS Messaging
Send simple text message
API: https://api.xcall.com.ng/v3/smsThis API enables you to send a text message (same message) to one or multiple recipients.
Request Parameters
Parameter | Type | Description |
---|---|---|
broadcastName | string | A name or title that describes the SMS broadcast. |
from | string | Sender ID for the message. It can be alphanumeric or numeric. Alphanumeric sender ID length should be between 3 and 11 characters. Numeric sender ID length should be between 3 and 14 characters. |
to | array_string | Array of destination (recipients') phone numbers in international format. |
smsText | string | Text of the message that will be sent. |
flash | boolean | Can be true or false. If the value is set to true, a flash SMS will be sent. Otherwise, a normal SMS will be sent. The default value is false. |
sendAt | string | The unix timestamp at which the message should be sent. Default is to send message immediately. |
notifyUrl | string | The URL on your server to which delivery report will be sent. |
Request Example
POST /v3/sms HTTP/1.1
Host: https://api.xcall.com.ng
Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==
Content-Type: application/json
Accept: application/json
{
"from":"XYZ",
"to":[
"2347031234567",
"2348057654321"
],
"smsText": "This is a test SMS",
"notifyUrl": "http://mydomain.com/sms/report"
}
curl -X POST \
-H "Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"from":"XYZ",
"to":[
"2347031234567",
"2348057654321"
],
"smsText": "This is a test SMS",
"notifyUrl": "http://mydomain.com/sms/report"
}' "https://api.xcall.com.ng/v3/sms"
<?php
/* Define sender ID
$from= "XYZ";
/* populate destination array. */
$to = array("2347031234567", "2348057654321");
$smsText = "This is a test SMS";
$notifyUrl= "http://mydomain.com/sms/report";
$requestData = array(
"from" => $from,
"to" => $to,
"smsText" => $smsText,
"notifyUrl" => $notifyUrl,
"sendAt" => "567889900" /* Unix timestamp to send text message. Defaut is to begin immediately. */
);
/* convert requestData to json format */
$requestData = json_encode($requestData);
/* Make API request */
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.xcall.com.ng/v3/sms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $requestData,
CURLOPT_HTTPHEADER => array(
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json",
"accept: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response on Success
HTTP/1.1 200 OK
Content-Type: application/json
{
"result":"OK",
"description":"Request accepted",
"broadcastId":"1315145",
"messages":[
{
"to":"2347031234567",
"status": "PENDING",
"messageId": "145698"
},
{
"to":"2348057654321",
"status": "PENDING",
"messageId": "605569"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
result | string | Indicates the result of the request. Possible values are:
"OK" - indicates that API request accepted. |
description | string | A description of the result. |
broadcastId | string | The ID that uniquely identifies the request. You can use this ID to retrieve delivery report and call log. |
messages | array-string | An array of message objects. One object per message. Includes:
to - The message destination phone number.
|