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 utilisé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.

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

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.

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

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

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

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

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}]

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>

Il est possible d’utiliser différemment l’API pour avoir l’ensemble des événements, depuis la présentation de l’appel, y compris avant le décroché, durant la sonnerie ou le message de pré-décroché

L’utilisation de l’API nécessite aussi les deux étapes décrites ci-dessus : l’authentification en générant un token, puis l’appel à l’API, en utilisant le token préalablement créé.

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 correspondant à votre compte API (Si vous n’en n’avez pas, veuillez en faire la demande).

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.

Sous la forme, avec CURL :

curl -X POST -u "<login>:<password>" -H "Content-Type: application/json" -d '{"ip":"<ip>", "user_type":"api"}' https://api.axialys.com/vm/token

Voici un exemple d’utilisation

https://voice-management.axialys.com/labo/index.htm?id_client=<id_client>&id_session=<id_session>

Pour tester, il vous suffit de remplacer id_client par celui que l’on vous a founit et id_session avec celui qui vous a été transmis par la génération du token, pour voir défiler l’ensemble des évènements de son compte.