L’Agent Availability API dà a chi ha un numero CallFactory un accesso diretto ai dati sullo stato degli operatori, da usare nel proprio software.
Si usa per esempio per mostrare sul sito, in tempo reale, quali operatori sono disponibili al telefono.
Qui sotto trovi le chiamate disponibili e le risposte che ricevi.
Nota: questa documentazione è pensata per programmatori che conoscono PHP, Python o un altro linguaggio, sanno lavorare con le API e sanno richiedere ed elaborare dati XML.
Panoramica
Con l’Agent Availability API leggi lo stato degli operatori dal tuo software.
Ecco le chiamate disponibili.
Chiamate
ivr.getAgentAvail
Indica se un particolare interno è occupato.
Url: https://api.belfabriek.nl/xml/agent/xml.asp
In:
- accountPin - PIN dell’account cliente
- extensionId - ID dell’interno (noto anche come ID Agente)
Out:
- available - se l’agente è abilitato (0 = no, 1 = sì)
- availReason - informazioni aggiuntive sullo stato dell’agente (ad es. “in pausa” o “in gestione”)
- extension - il numero di telefono attuale a cui questo interno si collega
general.getExtensionStatus
Restituisce lo stato attuale di un agente.
Url: https://api.belfabriek.nl/xml/agent/xml.asp
In:
- supId - ID supervisore
- manId - ID manager
- custId - ID account
- extId - ID interno
Out:
- status
- calling - connessione in corso
- called - connessione stabilita
- wrapup - connessione in fase di chiusura
- idle
Come utilizzare queste chiamate
Queste chiamate si fanno come richieste HTTP POST con pacchetti XML RPC. Negli esempi qui sotto ti mostriamo come, con il codice di esempio.
HTTP Post via XML RPC
Invii un pacchetto XML RPC all’URL indicato, specificando il nome della funzione.
Ecco come appare un messaggio XML RPC inviato al nostro server XML
RPC:<?xml version="1.0" encoding="iso-8859-1"?>
<methodCall>
<methodName>funzione.nome</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>Il nostro server XML RPC deve ricevere tutto nel formato XML
RPC corretto.
Inoltre il server si aspetta tutti i parametri come stringhe.
Ecco un esempio della risposta che ricevi dal nostro server XML RPC:<?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>## Esempi
Qui ti mostriamo come usare queste chiamate con PHP e curl. In qualsiasi altro linguaggio di programmazione funzionano in modo simile.
ivr.getAgentAvail
Ecco un esempio di chiamata valida a ivr.getAgentAvail 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();
?>
La risposta può essere questa:<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>3902XXXXXXX</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>Il valore sotto <name>extension</name> contiene il numero di telefono attuale a cui si collega questo interno:<value>
<string>31201234567</string>
</value>### general.getExtensionStatus
Ecco un esempio di chiamata valida a
general.getExtensionStatus 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();
?>
La risposta può essere questa:<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>Available</name>
<value>
<string>called</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>## Combinare le due chiamate
Usando insieme queste due chiamate ottieni lo stato esatto di un interno o di un operatore.
Parti dalla chiamata ivr.getAgentAvail. Se l’interno non è disponibile (available = 0), la risposta availReason ti dice perché.
I valori possibili di availReason sono, tra gli altri, “pause” (l’operatore è in pausa e al momento non accetta chiamate) e “-” (l’operatore non è connesso o per un altro motivo non è disponibile).
Se l’interno è disponibile (available = 1), controlli il suo stato con la chiamata general.getExtensionStatus.
Se lo stato è “calling” o “called”, l’operatore è al telefono. Altrimenti è disponibile o lo sarà a breve per le chiamate in arrivo.
Come gestire i diversi stati dipende dalla tua implementazione e dai suoi requisiti.