API Documentation

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

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/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: 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/callReport

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

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: finished running scheduled (Broadcast is scheduled to start at later time) paused cancelled
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/sms

This 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. "ERROR" - indicates that API request failed.
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. 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.