Employee Availability API

The Employee Availability API gives you direct access to endpoint status data for your own integrations. A common use is showing the real-time availability of team members on your website.

Note: This documentation is intended for developers with experience in PHP, Python, or similar languages, working with APIs, and processing XML data.

Available calls

ivr.getAgentAvail

Indicates whether a particular endpoint is busy.

URL: https://api.belfabriek.nl/xml/agent/xml.asp

In:

• accountPin - Customer account PIN
• extensionId - Endpoint ID

Out:

• available - whether the agent is enabled (0 = no, 1 = yes)
• availReason - Additional information about the status of the agent (e.g. “paused” or “handling”)
• endpoint - the current phone number this endpoint connects to

general.getExtensionStatus

Returns the current status of an agent.

URL: https://api.belfabriek.nl/xml/agent/xml.asp

In:

• supId - supervisor Id
• manId - Manager Id
• custId - account Id
• extId - endpoint Id

Out:

• status
• calling - connecting
• called - connection established
• wrapup - connection is in wrapup
• idle

How to use these calls

These calls are made as HTTP POST requests with XML-RPC packets. The examples below show how to do that, including example code.

HTTP Post via XML RPC

You post an XML-RPC packet to the URL above. The packet must name the function.

Example of what an XML RPC message to our XML RPC server looks like:

<?xml version="1.0" encoding="iso-8859-1"?>

<methodCall>

<methodName>function.name</methodName>

<params>

<param>

<value>

<struct>

<member>

<name>param1</name>

<value><string>value1</string></value>

</member>

<member>

<name>param2</name>

<value><string>value2</string></value>

</member>

</struct>

</value>

</param>

</params>

</methodCall>

Our XML-RPC server must always receive everything in the correct XML-RPC format, and it expects all parameters as strings.

An example of an XML RPC response from our XML RPC server as you would receive it:

<?xml version="1.0" encoding="iso-8859-1"?>

<methodResponse>

<params>

<param>

<value>

<struct>

<member>

<name>param1</name>

<value><string>value1</string></value>

</member>

<member>

<name>param2</name>

<value><string>value2</string></value>

</member>

</struct>

</value>

</param>

</params>

</methodResponse>

Examples

In this section we will show how to use these calls using PHP and curl. These calls can be made in a similar way in any other programming language.

ivr.getAgentAvail

The following is an example of a valid ivr.getAgentAvail call in PHP:

<?php

$accountPin = 'xxxxx'; //replace value with your own value

$extensionId = 'xxxxx'; //replace value with your own value

$url = 'https://api.belfabriek.nl/xml/agent/xml.asp';

$xml_data = "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>

<methodCall>

<methodName>ivr.getAgentAvail</methodName>

<params>

<param>

<value>

<struct>

<member>

<name>accountCode</name>

<value><string>$accountPin</string></value>

</member>

<member>

<name>extensionId</name>

<value><string>$endpoint</string></value>

</member>

</struct>

</value>

</param>

</params>

</methodCall>";

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, $url);

curl_setopt($curl, CURLOPT_PORT , 80);

curl_setopt($curl, CURLOPT_POST, 1);

curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));

curl_setopt($curl, CURLOPT_POSTFIELDS, $xml_data);

curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$data = curl_exec($curl);

curl_close($curl);

header("Pragma: public");

header("Expires: 0");

header("Cache-Control: must-revalidate, post-check=0, pre-check=0");

header("Cache-Control: private", false);

header("Content-Transfer-Encoding: binary");

header("Content-Type: text/xml charset=UTF-8");

echo $data;

die();

?>

The response would look something like this:

<methodResponse>

<params>

<param>

<value>

<struct>

<member>

<name>available</name>

<value>

<i4>0</i4>

</value>

</member>

<member>

<name>availReason</name>

<value>

<string>-</string>

</value>

</member>

<member>

<name>endpoint</name>

<value>

<string>31201234567</string>

</value>

</member>

</struct>

</value>

</param>

</params>

</methodResponse>

The value under <name>endpoint</name>:

<value>

<string>31201234567</string>

</value> is the endpoint number

general.getExtensionStatus

The following is an example of a valid general.getExtensionStatus call in PHP:

<?php

ini_set('display_errors', 'On');

$supId = 'x'; //replace value with your own value

$manId = 'x'; //replace value with your own value

$customerId = 'xxxxx'; //replace value with your own value

$extId = 'xxxxx'; //replace value with your own value

$url = 'https://api.belfabriek.nl/xml/agent/xml.asp';

$xml_data = "<?xml version='1.0'?>

<methodCall>

<methodName>general.getExtensionStatus</methodName>

<params>

<param>

<value>

<struct>

<member>

<name>supId</name>

<value><string>$supId</string></value>

</member>

<member>

<name>manId</name>

<value><string>$manId</string></value>

</member>

<member>

<name>accountCode</name>

<value><string>$customerId</string></value>

</member>

<member>

<name>extensionId</name>

<value><string>$extId</string></value>

</member>

</struct>

</value>

</param>

</params>

</methodCall>";

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, $url);

curl_setopt($curl, CURLOPT_PORT , 80);

curl_setopt($curl, CURLOPT_POST, 1);

curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));

curl_setopt($curl, CURLOPT_POSTFIELDS, $xml_data);

curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$data = curl_exec($curl);

curl_close($curl);

header("Pragma: public");

header("Expires: 0");

header("Cache-Control: must-revalidate, post-check=0, pre-check=0");

header("Cache-Control: private", false);

header("Content-Transfer-Encoding: binary");

header("Content-Type: text/xml charset=UTF-8");

echo $data;

die();

?>

The response would look something like this:

<methodResponse>

<params>

<param>

<value>

<struct>

<member>

<name>Available</name>

<value>

<string>called</string>

</value>

</member>

</struct>

</value>

</param>

</params>

</methodResponse>

Combining the two calls

We can use these two calls together to get the exact current status of an endpoint or agent.

We start with the ivr.getAgentAvail call. The response’s availReason will tell us everything we need to know if the endpoint is not available (available = 0).

Possible availReasons include “pause” (the agent is taking a break and currently not accepting calls), or “-” (the agent is currently not logged in or otherwise not available).

If the endpoint is available (available = 1), we want to probe further using the general.getExtensionStatus call.

If the status is either “calling” or “called”, we know the agent is on a call. Otherwise, they are or will soon be available for incoming calls.

How you want to handle different statuses depends a lot on your exact implementation and its requirements.