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:   api.xcall.com.ng/v2/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
(required)
stringA name or title that describes a 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 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 /tts/3/multi HTTP/1.1
Host: https:api.xcall.com.ng/call
Authorization: Basic c2FtbXllYmlubmVAZ21haWwuY29tOjRpNnk2ZzQ==
Content-Type: application/json
Accept: application/json
{ 
    "from":"2349081235467",
    "to":[ 
        "2347031234567",
        "2348057654321",
        "2348063246574"
    ],
    "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":"2349081235467",
        "to":[ 
            "2347031234567",
            "2348057654321",
            "2348063246574"
        ],
        "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/call"
                            
                        
                            
<?php
/* Define  sender ID
$from= "2348191234567";

/* populate destination  array. */
$to = [];
$to[]= "2347031234567";
$to[]= "2348057654321";
$to[]= "2348063246574";

/* 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/api/calls",
  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/v2/ivr

This API endpoint makes outbound interactive voice calls to one or multiple phone numbers. You can send automated phone calls to multiple recipipients, 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 /tts/3/multi HTTP/1.1
Host: https:api.xcall.com.ng/ivr
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

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.

Getting Delivery Reports

Path:   https://api.xcall.com.ng/v2/call_reports

This 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

ParametersTypeDescription
broadcastId
(required)
intThe ID which uniquely identifies the broadcast.
limit intMaximum number of records to return. Default value is 50.
offsetintOffset to the start of the record. Useful for pagination. Default is 0.


Response Parameters

ParametersTypeDescription
resultstringIndicates result of API request. "OK" if successful and "ERROR" if unsuccessful.
msgstringA description of the result.
broadcastIdintReturns the ID of the broadcast.
broadcastNameintReturns the name of the broadcast.
fromstringThe sender ID
statusstringThe current status of the broadcast. Possible values are:
  • Completed
  • Running
  • Scheduled (Broadcast is scheduled to start at later time)
  • Paused
  • Cancelled
dstCountstringThe total number of destination phone numbers (recipients).
dialedCountstringThe number of destination numbers processed.
answeredCallsstringThe number of calls answered.
remainingCallsstringThe number of destination numbers remaining.
startTimestringThe time (in unix timestamp) that the broadcast started.
endTimestringThe time (in unix timestamp) that the broadcast completed.
maxCallLengthstringThe maximum call duration in seconds.
billedCreditstringThe cost of the broadcast.
offSetintOffset to the start of the record.
limitintMaximum number of records to return.
callLogobjectcontains call records
dialedTimeintThe unix timestamp when call was first attempted.
callResultstringIndicates whether call was answered or not.
ivrResponsestringProvides the dtmf response to each question of an IVR call.

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 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.