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.