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
{
"broadcastName": "Test call",
"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. |
Receiving Voice Delivery Reports (via webhook)
You can receive delivery reports for Voice broadcasts and outbound IVR automatically when the broadcast is completed. All you need to do is specify a webhook URL (in the notifyUrl parameter) when you create the outbound voice broadcast or IVR. The delivery report is sent to the webhook URL in JSON format and it includes the following fields:
Payload Example
Parameters | Type | Description |
---|---|---|
report | Array of objects | Array of objects containing the delivery report. |
broadcastId | string | The ID that uniquely identifies the voice broadcast session. |
name | string | Name of the broadcast. |
type | string | The type of Xcall Voice service. |
dateCreated | string | The date the broadcast was created. Time format is unix timestamp. |
startTime | string | Tells when the voice broadcast started. Time format is unix timestamp. |
destinations | integer | The number of destination phone numbers. |
status | string | The status of the broadcast. |
endTime | string | The time the broadcast completed. Time format is unix timestamp. |
msgFile | string | The filename of the audio message file. |
callLog | object | Data about the voice calls. |
sessionId | string | The ID that uniquely identifies the call session. |
from | string | The phone number that appears as caller ID. |
to | string | The destination phone number. |
sentAt | string | Tells when the Voice message call was established. Time format is unix timestamp. |
result | string | Tells the result of the voice message call. 'Delivered' or 'Not delivered' |
disposition | string | The disposition of the destination number. 'Answered', 'Busy', 'Ringing, no answer', Not reachable. |
answerTime | string | Tells when the call was answered. Time format is unix timestamp. |
duration | string | The duration of the call in seconds. |
ivrResponse | object | IVR prompts and response data. |
Examples
{
"report": {
"broadcastId": "31940",
"name": "apiTest",
"type": "simple broadcast",
"dateCreated": "1684887999",
"startTime": "1684887999",
"endTime": "1684888093",
"status": "completed",
"destinations": 2,
"msgFile": "tts_audio_4n4h3k5t8y9b.mp3",
"callbackData": null,
"callLog": [
{
"sessionId": "6231407",
"from": "2348037891009",
"to": "2348130429229",
"sentAt": "1684888091",
"result": "Not Delivered",
"disposition": "Busy",
"answerTime": null,
"duration": null
},
{
"sessionId": "6231408",
"from": "2348037891009",
"to": "2348187957011",
"sentAt": "1684888016",
"result": "Delivered",
"disposition": "Answered",
"answerTime": "1684888016",
"duration": "2.5069"
}
]
}
}
<?php
/* Use file_get_contents() function to receive the json payload in a readable format. */
$json_data = file_get_contents("php://input"); /* Use file_get_contents() function to receive the json payload*/
$array_data = json_decode($json_array, true); /* Use json_decode() function to decode JSON data in PHP. */
/* array_data contains the delivery report data in a php array. You can do with it whatever you please. */
?>
Getting Delivery Reports (via query)
Path: https://api.xcall.com.ng/v3/voiceReportThis API endpoint allows you to get delivery reports for sent Voice messages, and outbound IVR (without notifyUrl request parameter). Delivery reports are returned only once. Additional delivery report request will return an empty collection.
Request Parameters
Parameters | Type | Description |
---|---|---|
broadcastId (required) | integer | The ID which uniquely identifies the broadcast request. |
limit | integer | Maximum number of records to return. Default value is 50. |
offset | string | 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. |
report | Array of objects | Array of objects containing the delivery report. |
broadcastId | string | The ID that uniquely identifies the voice broadcast session. |
name | string | Name of the broadcast. |
type | string | The type of Xcall Voice service. |
dateCreated | string | The date the broadcast was created. Time format is unix timestamp. |
startTime | string | Tells when the voice broadcast started. Time format is unix timestamp. |
destinations | integer | The number of destination phone numbers. |
status | string | The status of the broadcast. |
endTime | string | The time the broadcast completed. Time format is unix timestamp. |
msgFile | string | The filename of the audio message file. |
maxCallLength | string | The maximum permissible call duration in seconds. |
offSet | int | Offset to start of record. |
limit | int | Maximum number of records to return. |
callLog | object | Data about the voice calls. |
sessionId | string | The ID that uniquely identifies the call session. |
from | string | The phone number that appears as caller ID. |
to | string | The destination phone number. |
sentAt | string | Tells when the Voice message call was established. Time format is unix timestamp. |
result | string | Tells the result of the voice message call. 'Delivered' or 'Not delivered' |
disposition | string | The disposition of the destination number. 'Answered', 'Busy', 'Ringing, no answer', Not reachable. |
answerTime | string | Tells when the call was answered. Time format is unix timestamp. |
duration | string | The duration of the call in seconds. |
ivrResponse | object | IVR prompts and response data. |
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 webhook 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.
|