Mit der Agent Availability API greifen Inhaber von Telefonnummern direkt auf die Statusdaten ihrer Mitarbeiter zu und verarbeiten sie in ihrer eigenen Software.
Unternehmen nutzen die API zum Beispiel, um auf ihrer Website anzuzeigen, welche telefonischen Berater gerade erreichbar sind.
Welche Aufrufe es gibt und welche Ergebnisse sie liefern, steht in der Dokumentation unten.
Achtung: Die Dokumentation richtet sich an Entwickler mit Erfahrung in PHP, Python oder einer anderen Programmiersprache, im Umgang mit APIs und in der Verarbeitung von XML-Daten.
Übersicht
Unten finden Sie die verfügbaren Aufrufe.
Aufrufe
ivr.getAgentAvail
Gibt an, ob eine bestimmte Durchwahl besetzt ist.
Url: https://api.belfabriek.nl/xml/agent/xml.asp
Eingabe:
- accountPin: PIN des Kundenkontos
- extensionId: ID der Durchwahl (auch Mitarbeiter-ID genannt)
Ausgabe:
- available: ob der Mitarbeiter verfügbar ist (0 = nein, 1 = ja)
- availReason: zusätzliche Angaben zum Status des Mitarbeiters (zum Beispiel „paused“ oder „handling“)
- extension: die Telefonnummer, mit der diese Durchwahl gerade verbunden ist
general.getExtensionStatus
Gibt den aktuellen Status eines Mitarbeiters zurück.
Url: https://api.belfabriek.nl/xml/agent/xml.asp
Eingabe:
- supId: Supervisor-ID
- manId: Manager-ID
- custId: Konto-ID
- extId: ID der Durchwahl
Ausgabe:
- status
- calling: Verbindung wird hergestellt
- called: Verbindung hergestellt
- wrapup: Verbindung wird beendet
- idle
So senden Sie die Aufrufe
Die Aufrufe werden als HTTP-POST mit XML-RPC-Paketen gesendet. In den Beispielen unten zeigen wir, wie das geht, mit Beispielcode.
HTTP-Post über XML-RPC
Sie senden ein XML-RPC-Paket an die angegebene URL und geben darin den Namen der Funktion an.
So sieht eine XML-RPC-Nachricht an unseren XML-RPC-Server aus:<?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>Unser XML-RPC-Server erwartet alle Daten immer im korrekten
XML-RPC-Format.
Außerdem erwartet der XML-RPC-Server alle Parameter als Strings.
So sieht eine Antwort unseres XML-RPC-Servers aus:<?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>## Beispiele
In diesem Abschnitt zeigen wir die Aufrufe mit PHP und curl. In anderen Programmiersprachen funktionieren sie auf die gleiche Weise.
ivr.getAgentAvail
Ein gültiger ivr.getAgentAvail-Aufruf 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>$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();
?>
Die Antwort sieht ungefähr so aus:<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>Der Wert unter<name>extension</name>:<value>
<string>31201234567</string>
</value>
ist die Zielnummer.
general.getExtensionStatus
Ein gültiger general.getExtensionStatus-Aufruf 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();
?>
Die Antwort sieht ungefähr so aus:<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>Available</name>
<value>
<string>called</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>## So kombinieren Sie die Aufrufe
Mit beiden Aufrufen zusammen ermitteln Sie den genauen Status einer Durchwahl oder eines Mitarbeiters.
Beginnen Sie mit dem Aufruf ivr.getAgentAvail. Ist die Durchwahl nicht verfügbar (available = 0), sagt Ihnen der Wert „availReason“, warum.
Mögliche Werte für availReason sind „pause“ (der Mitarbeiter macht Pause und nimmt keine Anrufe an) und „-“ (der Mitarbeiter ist nicht angemeldet oder aus einem anderen Grund nicht verfügbar).
Ist die Durchwahl verfügbar (available = 1), fragen Sie mit dem Aufruf general.getExtensionStatus weiter nach.
Ist der Status „calling“ oder „called“, telefoniert der Mitarbeiter gerade. Andernfalls ist er für eingehende Anrufe verfügbar oder wird es gleich sein.
Wie Sie mit den verschiedenen Status umgehen, hängt von Ihrer eigenen Anwendung ab.