Cette API permet de recevoir en temps réel un flux d’événements en rapport avec tous les aspects du fonctionnement du Voice Management : agents, files d’attentes, acheminements. Elle peut être tuilisée pour divers usages, et notamment la production de dashboards de supervision.

Elle est basée sur le protocole Socket.IO

L’utilisation de l’API nécessite deux étapes :

  1. une première étape d’authentification, sous forme de requête HTTP normale
  2. l’utilisation à proprement parler, via la librairie Socket.IO, en utilisant l’authentification créée au point précédent.

Avant de pouvoir se connecter à notre serveur de notifications, il est nécessaire d’obtenir un token d’authentification qui sera valable 2h. La requête doit être effectuée à partir de la machine où sera effectué le traitement des notifications. La vérification étant effectuée via le token et l’IP.

L’authentification nécessite l’usage d’un login/password de type “superviseur”.

On effectue donc une requête POST en y configurant un header JSON avec les credentials afin d’obtenir le token qui sera utilisé pour s’authentifier auprès du serveur de notifications.

Les données à inclure dans le JSON sont :

  • requete: init
  • header:
    • count_type: supervisor
    • login: « login »
    • password: « password »
  • msg: (vide)

Exemple de demande d’authentification avec CURL :

curl -X POST -H "X-JSON: {\"requete\":\"init\",\"header\": 
{\"login\":\"xxxxx\",\"password\":\"xxx\",\"account_type\":\"supervisor\"},\"msg\":{}}" 
https://voice-management.axialys.com/ws/

Cette requête retourne dans un objet JSON toutes les informations nécessaires à la réception des notifications, la configuration des groupes et des agents.

Les principales informations utiles sont :

  • ops (id, nom, groupes[])
  • groupes (id, nom)
  • trunks (id, nom)
  • pauses (id, value)
  • target (id du superviseur)
  • id_session

Les deux derniers paramètres sont l’identifiant du compte de supervision (target) et le token (id_session) nécessaires à l’authentification, voir ci-après.

 

4.1 Connexion

Le flux de notifications utilise le protocole de la librairie Javascript Socket.IO. Les exemples ci-après sont en Javascript, mais toute librairie compatible avec ce protocole devrait fonctionner.

Une fois l’authentification effectuée et le token d’authentification obtenu, on peut se connecter au serveur de notifications pour recevoir les événements en temps réel.

Il convient de positionner un callback sur les événements de type update, et ensuite de demander le démarrage du flux par un message de type init.

socket = io.connect() ;
socket.on(‘update’, function(data) { // traitement de l'événement })
socket.emit('init', 'supervisor', <id_superviseur>, <id_session>);

4.2 Evénements

Les données sont transmises sous forme d’un objet JSON, avec le nom de l’événement qui sera toujours «update» et une structure de la forme suivante :

  • cpt: numéro de l’événement
  • elapse: temps écoulé depuis l’événement
  • event:
    • event: insert_call
    • type_notification: queue |operator |UI |trunk
  • ts: timestamp auquel l’événement a été envoyé

Il existe 5 types d’événements, détaillés ci-après:

  • operator: concerne l’état des communications d’un agent.
  • UI: concerne l’état de l’interface de l’agent, login / pauses…
  • PUSHCALL: une demande a été effectuée pour demander à un agent d’effectuer un appel sortant.
  • queue: informations sur une file de type agents.
  • trunk: informations sur une file de type acheminement.

4.2.1 Evénement operator

Permet d’obtenir des informations sur le statut d’un agent:

Exemple:

{“msg”: {“status”: “connected”, “rec”: 1, “call_duration”: 0, “caller_id_num”: “3363441111”, “step”: 1, “id_queue”: 0, “id_call”: -17137, “id_operator”: 8, “id_client”: 3}, “type_notification”: “operator”, “event”: “status”}

Valeurs disponibles pour les principales variables:

  • call_duration: durée de l’appel
  • caller_id_num: numéro de l’appelant
  • id_call: identifiant de l’appel
  • id_operator: id de l’agent concerné
  • id_queue: id de la file associé à l’appel en cours
  • rec: appel enregistré
  • statut
    • available: agent disponible
    • ringing: agent en sonnerie
    • calling: appel effectué
    • connected: appel en cours
    • unavailable: état inconnu

4.2.2 Evénement UI

Permet d’obtenir des informations sur le login/logout/pause ou d’autres de types d’informations en lien avec l’interface des agents.

Exemple login:

{"msg": {"supp": "", "id_operator": 1, "id_client": 1}, "type_notification": "UI", "event": "login"}

Exemple de pause: {“msg”: {“supp”: “user1”, “id_operator”: 1, “id_client”: 1}, “type_notification”: “UI”, “event”: “pause”}

Valeurs disponibles pour les principales variables:

  • event:
    • login: connexion de l’agent
    • logout: déconnexion de l’agent
    • pause: événement de type pause
  • id_operator: identifiant de l’agent concerné
  • supp: informations complémentaire, notamment identifiant du type de pause

4.2.3 Evénement «queue»

Permet d’obtenir des informations sur le login/logout ou d’autres de types d’informations en lien avec l’interface, type utilisateur en pause.

Exemple d’appel entrant:

{"msg": {"call_duration": 43, "caller_id_num": "33761433333", "priority": 100, "id_queue": 391, "id_call": 26, "vip_rate": 1, "duration_in_queue": 0, "id_client": 174808}, "type_notification": "queue", "event": "insert_call"}

Exemple de mise en relation:

{"msg": {"status": "connected", "call_duration": 0, "caller_id_num": "335497", "step": 1, "id_queue": 8, "id_call": -1713, "id_operator": 2, "id_client": 1}, "type_notification": "queue", "event": "connect_call"}

Exemple de sortie de file d’attente:

{"msg": {"id_call": 26901513, "id_queue": 1023, "id_client": "164645"}, "type_notification": "queue", "event": "delete_call"}

Valeurs disponibles pour les principales variables:

  • call_duration: durée de l’appel
  • caller_id_num: numéro de l’appelant
  • duration_in_queue: durée d’attente dans la file
  • event:
    • connect_call: mise en relation
    • delete_call: appel terminé
    • insert_call: appel entrant dans file
  • id_call: identifiant de l’appel
  • id_operator: id de l’agent concerné
  • id_queue: id de la file associé à l’appel en cours
  • rec: appel enregistré
  • statut
    • available: agent disponible
    • ringing: agent en sonnerie
    • calling: appel effectué
    • connected: appel en cours
    • unavailable: état inconnu

4.2.4 Evénement «trunk»

Permet d’obtenir des informations sur les appels de type acheminement

Exemple ajout d’appel:

{"msg": {"call_duration": 0, "id_trunk": 346223, "caller_id_num": "33783655555", "id_call": 269, "duration_in_queue": 0}, "type_notification": "trunk", "event": "insert_call"}

Exemple de mise en relation

{"msg": {"status": "connected", "call_duration": 0, "id_trunk": "345940", "caller_id_num": "33980689888",  "id_call": "26903925"}, "type_notification": "trunk", "event": "connect_call"}

Exemple fin d’appel:

{"msg": {"id_call": 2690, "id_trunk": 34}, "type_notification": "trunk", "event": "delete_call"}

Valeurs disponibles pour les principales variables:

  • caller_id_num: numéro de l’appelant
  • call_duration: durée de l’appel
  • id_call: identifiant de l’appel
  • id_trunk: identifiant du compte d’acheminement
  • event:
    • insert_call: ajout d’un appel dans une file
    • connect_call: mise en relation
    • delete_call: fin appel

4.3 Exemple avec un message complet

Ci-dessous un exemple de message complet tel que le JSON sera reçu.

Exemple:

["update",{"ts":1547651821,"elapse":0,"event":{"msg":{"status":"transfert_start","id_operator":1,"stype":3,"id_client":164645,"id_call":"26"},"type_notification":"operator","event":"status"},"cpt":2297}]

4.4 Exemple d’appel

Au préalable, il faut générer un token et ajouter l’identifiant du superviseur ([target]) à la variable “id_sup” et l’identifiant de la session ([id_session]) à la variable “id_session”.

<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8">
<title>Demo socket.io</title>
<script src="./socket.io.js" crossorigin="anonymous"></script>
<script src="https://code.jquery.com/jquery-3.2.1.min.js" crossorigin="anonymous"></script>
<script>
 
var id_sup = [target] ;
var id_session = [id_session] ;
 
$(document).ready(function () {
	var socket = io.connect("https://voice-management.axialys.com", {path:"/socket.io/"});
	socket.on('connect', function() {
		console.log("ready") ;
		$("#text").append("<p>ready</p>") ;
		socket.emit('init', 'supervisor', id_sup, id_session);
	});
 
	socket.on('update', function(data) {
		$("#text").append("<p>"+JSON.stringify(data)+"</p>") ;
		console.log(data) ;
	}) ;
 
	console.log([id_sup, id_session]) ;
    socket.emit('init', 'supervisor', id_sup, id_session);
}) ;
</script>
</head>
<body>
Mon test:
<div id="text"></div>
</body>
</html>