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.

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.

ParameterTypeDescription
Authorization
(Required)
stringMust include the word "Basic" followed by the auth token you generated. Should look like this:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-Type
(Required)
stringThe requests content type. Must be application/json
Accept
(Required)
array_stringThe requests response type. Must be application/json

Voice Messaging


Creating Outbound Calls

Path:   https://api.xcall.com.ng/v3/call

This API endpoint sends automated calls to one or multiple phone numbers and plays a recorded audio message or text-to-speech message.

Request Parameters

ParameterTypeDescription
broadcastName
(optional)
stringA name or title that describes the broadcast.
from
(optional)
stringSender 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_stringArray of destination (recipients') phone numbers. Phone numbers must be in international format. (Example: "2347031234567")
ttsMsg
stringText-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
stringDefines 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.
audioFileUrlstringYou 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 timestampUnix timestamp that specifies the time to begin the calls. If startTime is not set, the calls will begin immediately.
notifyUrl
stringThe 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

ParameterTypeDescription
resultstringIndicates the result of an API request. The value is "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdstringID that uniquely identifies the broadcast request. You can use this ID to retrieve delivery report and call log.
msgLengthintDuration (in seconds) of voice message
dstCountintNumber of call recipients or destination phone numbers.
reservedCreditintThe 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/ivr

This 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: 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

ParameterTypeDescription
broadcastNamestringA name or title that describes the broadcast.
templateId
(required)
stringID of the IVR template that defines an outbound IVR call/broadcast.
to
(required)
array-stringArray of destination (recipients') phone numbers. Phone numbers must be in international format. (Example: "2347031234567")
fromstringSender ID. This number will show on recipients' phone numbers when the call arrives. Only verified phone numbers are accepted.
maxCallLengthint Maximum permissible duration of IVR call in seconds. The system will terminate the call when this time elapes. Default is 120 seconds.
customDataarray_string Array of values that corresponds to custom variables in IVR template. Array keys must match the variable names in IVR template.
startTimeUnix timestampUnix timestamp that specifies the time to begin the calls. If startTime is not set, the calls will begin immediately.
notifyUrlstringThe URL on your your server to which Delivery report will be sent.
maxRetriesintThe maximum number of retry attempts. Limit is 2.
waitTimeintThe 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

ParameterTypeDescription
resultstringIndicates the result of an API request. The value is "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdintID that uniquely identifies the request. With this ID you can retrieve the status and call records.
msgLengthintDuration (in seconds) of voice message
dstCountintNumber of call recipients or destination phone numbers.
reservedCreditintThe 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

ParametersTypeDescription
reportArray of objectsArray of objects containing the delivery report.
broadcastIdstringThe ID that uniquely identifies the voice broadcast session.
namestringName of the broadcast.
typestringThe type of Xcall Voice service.
dateCreatedstringThe date the broadcast was created. Time format is unix timestamp.
startTimestringTells when the voice broadcast started. Time format is unix timestamp.
destinationsintegerThe number of destination phone numbers.
statusstringThe status of the broadcast.
endTimestringThe time the broadcast completed. Time format is unix timestamp.
msgFilestringThe filename of the audio message file.
callLogobjectData about the voice calls.
sessionIdstringThe ID that uniquely identifies the call session.
fromstringThe phone number that appears as caller ID.
tostringThe destination phone number.
sentAtstringTells when the Voice message call was established. Time format is unix timestamp.
resultstringTells the result of the voice message call. 'Delivered' or 'Not delivered'
dispositionstringThe disposition of the destination number. 'Answered', 'Busy', 'Ringing, no answer', Not reachable.
answerTimestringTells when the call was answered. Time format is unix timestamp.
durationstringThe duration of the call in seconds.
ivrResponseobjectIVR 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/voiceReport

This 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

ParametersTypeDescription
broadcastId
(required)
integerThe ID which uniquely identifies the broadcast request.
limit integerMaximum number of records to return. Default value is 50.
offsetstringOffset 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

ParametersTypeDescription
resultstringIndicates result of API request. "OK" if successful.
reportArray of objectsArray of objects containing the delivery report.
broadcastIdstringThe ID that uniquely identifies the voice broadcast session.
namestringName of the broadcast.
typestringThe type of Xcall Voice service.
dateCreatedstringThe date the broadcast was created. Time format is unix timestamp.
startTimestringTells when the voice broadcast started. Time format is unix timestamp.
destinationsintegerThe number of destination phone numbers.
statusstringThe status of the broadcast.
endTimestringThe time the broadcast completed. Time format is unix timestamp.
msgFilestringThe filename of the audio message file.
maxCallLengthstringThe maximum permissible call duration in seconds.
offSetintOffset to start of record.
limitintMaximum number of records to return.
callLogobjectData about the voice calls.
sessionIdstringThe ID that uniquely identifies the call session.
fromstringThe phone number that appears as caller ID.
tostringThe destination phone number.
sentAtstringTells when the Voice message call was established. Time format is unix timestamp.
resultstringTells the result of the voice message call. 'Delivered' or 'Not delivered'
dispositionstringThe disposition of the destination number. 'Answered', 'Busy', 'Ringing, no answer', Not reachable.
answerTimestringTells when the call was answered. Time format is unix timestamp.
durationstringThe duration of the call in seconds.
ivrResponseobjectIVR prompts and response data.

SMS Messaging


Send simple text message

API:   https://api.xcall.com.ng/v3/sms

This API enables you to send a text message (same message) to one or multiple recipients.

Request Parameters

ParameterTypeDescription
broadcastNamestringA name or title that describes the SMS broadcast.
fromstringSender 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.
toarray_stringArray of destination (recipients') phone numbers in international format.
smsText
stringText of the message that will be sent.
flash
booleanCan 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
stringThe 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

ParameterTypeDescription
resultstringIndicates the result of the request. Possible values are:

"OK" - indicates that API request accepted.
"ERROR" - indicates that API request failed.

descriptionstringA description of the result.
broadcastIdstringThe ID that uniquely identifies the request. You can use this ID to retrieve delivery report and call log.
messagesarray-stringAn array of message objects. One object per message. Includes:

to - The message destination phone number.
status - Indicates the status of the message. Possible values are:

  • PENDING
  • DELIVERED
  • REJECTED
  • EXPIRED
messageId - The ID that uniquely identifies each message sent. You can use the message ID to map delivery reports to a specific message.