Medewerker Beschikbaarheid API
De Agent Availability API is bedoeld om telefoonnummer eigenaren low-level toegang te geven tot medewerkerstatusgegevens ten behoeve van custom implementaties in eigen software.
De API wordt o.a. gebruikt om medewerkerbeschikbaarheid 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.
Hieronder vindt u een overzicht van de beschikbare calls.
Calls
ivr.getAgentAvail
Geeft aan of een bepaald toestel bezet is.
Url: http://api1.belfabriek.nl/xml/agent/xml.asp
In:
- accountPin - Klant account-PIN
- extensionId - Toestel-ID (ook wel Medewerker-ID genoemd)
Out:
- available - of de medewerker beschikbaar is (0 = nee, 1 = ja)
- availReason - Bijkomende informatie over de status van de medewerker (bv. “paused” of “handling”)
- extension - het huidige telefoonnummer waarnaar dit toestel doorverbindt
general.getExtensionStatus
Geeft de huidige status van een medewerker terug.
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
De klant stuurt een XML RPC-pakket naar de opgegeven URL. De functienaam moet worden opgegeven.
Voorbeeld van hoe een XML RPC-bericht naar onze XML RPC-server eruitziet:
<?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>
Onze XML RPC-server moet alles altijd in het juiste XML RPC-formaat ontvangen.
Daarnaast verwacht de XML RPC-server alle parameters als strings te ontvangen.
Een voorbeeld van een XML RPC-antwoord van onze XML RPC-server zoals u het zou ontvangen:
<?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>
Voorbeelden
In deze sectie laten we zien hoe u deze calls kunt gebruiken met PHP en curl. Deze calls kunnen op een vergelijkbare manier in elke andere programmeertaal worden gemaakt.
ivr.getAgentAvail
Hieronder vindt u een voorbeeld van een geldige 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();
?>
Het antwoord ziet er ongeveer zo uit:
<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>
De waarde onder <name>extension</name>:
<value>
<string>31201234567</string>
</value> is het bestemmingsnummer
general.getExtensionStatus
Hieronder vindt u een voorbeeld van een geldige 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();
?>
Het antwoord ziet er ongeveer zo uit:
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>Available</name>
<value>
<string>called</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
Hoe deze calls te gebruiken
We kunnen deze twee calls samen gebruiken om de exacte huidige status van een toestel of medewerker te krijgen.
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).
Als het toestel beschikbaar is (available = 1), willen we verder onderzoeken met de 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.
Hoe u de verschillende statussen wilt afhandelen hangt sterk af van uw exacte implementatie en de vereisten ervan.