De Agent Availability API is bedoeld om servicenummer eigenaren low-level toegang te geven tot medewerkerstatusgegevens 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.

Overzicht

De Agent Availability API is bedoeld om servicenummer-eigenaren low-level toegang te geven tot medewerkerstatus-gegevens ten behoeve van custom implementaties in eigen software.

Hieronder vindt u een overzicht van de beschikbare calls.

Calls

ivr.getAgentAvail

Geeft aan of een bepaalde extensie bezet is.

Url: http://api1.belfabriek.nl/xml/agent/xml.asp

In:

  • accountPin - Klant account PIN
  • extensionId - Extensie-ID (ook wel Medewerker-ID genoemd)

Out:

  • available - of de medewerker ingeschakeld is (0 = nee, 1 = ja)
  • availReason - Aanvullende informatie over de status van de medewerker (bijv. “paused” of “handling”)
  • extension - het huidige telefoonnummer waarnaar deze extensie 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 - verbinding wordt gemaakt
  • called - verbinding tot stand gebracht
  • wrapup - verbinding wordt afgerond
  • idle - beschikbaar

Hoe deze calls te gebruiken

Deze calls worden gedaan als HTML Post calls met behulp van XML RPC packets. In de onderstaande voorbeelden laten we zien hoe u dit doet, inclusief voorbeeldcode.

HTTP Post via XML RPC

De klant stuurt een XML RPC packet 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 dient alles in het correcte XML RPC formaat te ontvangen.

Daarnaast verwacht de XML RPC server alle parameters als strings te ontvangen.

Een voorbeeld van een XML RPC response van onze XML RPC server zoals u deze 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 vergelijkbare wijze in elke andere programmeertaal worden gedaan.

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();

?>

De response ziet er dan ongeveer als volgt 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();

?>

De response ziet er dan ongeveer als volgt uit:

<methodResponse>

<params>

<param>

<value>

<struct>

<member>

<name>Available</name>

<value>

<string>called</string>

</value>

</member>

</struct>

</value>

</param>

</params>

</methodResponse>

Hoe deze calls samen te gebruiken

We kunnen deze twee calls samen gebruiken om de exacte huidige status van een extensie of medewerker op te vragen.

We beginnen met de ivr.getAgentAvail call. De availReason in de response vertelt ons alles wat we moeten weten als de extensie niet beschikbaar is (available = 0).

Mogelijke availReasons zijn onder andere “pause” (de medewerker neemt een pauze en accepteert momenteel geen oproepen) of “-” (de medewerker is momenteel niet ingelogd of anderszins niet beschikbaar).

Als de extensie wel beschikbaar is (available = 1), willen we verder onderzoeken met de general.getExtensionStatus call.

Als de status “calling” of “called” is, weten we dat de medewerker in gesprek is. Anders is de medewerker beschikbaar of binnenkort beschikbaar voor inkomende oproepen.

Hoe u de verschillende statussen wilt afhandelen, hangt sterk af van uw specifieke implementatie en de bijbehorende vereisten.