De 085/088/0800/0900 telefoonnummer maatschappij van Nederland
Medewerker Beschikbaarheid API
De Agent Availability API is bedoelt om servicenummer eigenaren low-level toegang te geven tot medewerker status gegevens ten behoeve van custom implementaties in eigen software.
De API wordt o.a. gebruikt om medewerker beschikbaarheid van telefonische consulenten in real time online te kunnen tonen.
Een overzicht van de beschikbare calls en te verwachten resultaten, vindt u in onze API documentatie hieronder.
Let op: deze documentatie is bedoeld voor programmeurs met ervaring in PHP, Python of andere programmeertalen, het werken met APIs en opvragen en verwerken van XML data.
Overview
The Agent Availability API is meant to give servicenumber owners low-level access to Agent Statuses for custom implementation in their own software.
Below is a list of of the available calls.
Calls
ivr.getAgentAvail
Indicates whether a particular extension is busy.
Url: http://api1.belfabriek.nl/xml/agent/xml.asp
In:
accountPin - Customer account PIN
extensionId - Extension ID (also referred to as Medewerker ID)
Out:
available - whether the agent is enabled (0 = no, 1 = yes)
availReason - Additional information about the status of the agent (eg "paused" or "handling")
extension - the current phone number this extension connects to
general.getExtensionStatus
Returns the current status of an agent.
Url: http://api1.belfabriek.nl/xml/agent/xml.asp
In:
supId - supervisor Id
manId - Manager Id
custId - account Id
extId - extension Id
Out:
status
calling - connecting
called - connection established
wrapup - connection is in wrapup
idle
How to use these calls
These calls are made as HTML Post calls using XML RPC packets. In the examples below we’ll show you how to do that, including example code.
HTTP Post via XML RPC
Customer posts a XML RPC packet to the specified URL. The function name must be specified.
Example of what an XML RPC message to our XML RPC server looks like:
<?xml version="1.0" encoding="iso-8859-1"?>
<methodCall>
<methodName>functie.naam</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 should always receive everything in the correct XML RPC format.
In addition the XML RPC server expects to receive 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 = 'http://api1.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>$extension</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>extension</name>
<value>
<string>31201234567</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
The value under <name>extension</name>:
<value>
<string>31201234567</string>
</value> is the destination 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 = 'http://api1.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>
How to use these calls
We can use these two calls together to get the exact current status of an extension or agent.
We start with the ivr.getAgentAvail call. The response’s availReason will tell us everything we need to know if the extension 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 extension 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.
