Guide voice management

LE GUIDE UTILISATEUR DE VOTRE SOLUTION CALL CENTER

Retour au guide

API notifications Voice Management

1 - Introduction

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

2 - Principe de fonctionnement

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.

3 - Authentification

3.1 - Authentification

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)
  • expire (date d’expiration au format yyyy-mm-ddthh-mm-ss.000000+GMT)
  • 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.

3.2 - Renouvellement du token d’authentification

Au lieu d’attendre l’expiration du token pour le renouveler (au risque de perdre éventuellement des évènements), il vous ait possible de le faire via la méthode suivante :

				
					curl -X POST -H ‘X-JSON: {\”requete\”:\”refresh_token\”,\”header\”:{\”id_session\”:\”XXXXXXXXXX\”},\”msg\”:{}}’ ‘https://voice-management.axialys.com/ws/’

Cette requête retourne dans un objet JSON id_session, ainsi que expire sous la forme “2021-01-28T14:25:55.914753+01:00”.

4 - Flux de notifications

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é
  • catchup: durée catchup après appel (renseigné uniquement lors de la fin d’un appel)
  • service: numéro du service lors de la sonnerie (définie uniquement lors de la sonnerie
  • statut
    • available: agent disponible
    • ringing: agent en sonnerie
    • calling: appel effectué
    • connected: appel en cours
    • unavailable: état inconnu
    • transfert_start: début d’un transfert d’appel
    • transfert_end: fin d’un transfert
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
    • unpause: sortie de pause
    • push: appel poussé vers l’interface de l’opérateur
    • push_cancel: tentative annulation des différents événements poussés vers l’opérateur
  • id_operator: identifiant de l’agent concerné
  • supp: informations complémentaire, notamment identifiant du type de pause

Variables spécifiques contenues dans “msg” et concernant le fait de pousser des événements vers l’interface du client (push).

  • retry_timeout: durée entre 2 essais
  • auto_timeout: timeout au bout duquel sera lancé l’appel si l’opérateur ne l’a pas lancé avant et qu’on a une demande de type “AUTO”
  • vars: variables
  • ring_timeout: temps de sonnerie
  • expire: expiration attribution
  • unassign_timeout: timeout pour dés-attribution appel
  • retries: nombre d’essais restants
  • priority: priorité de l’appel (1 à 100)
  • e164: numéro à mettre en relation avec l’opérateur
  • type:
    • AUTO: lancement de l’appel automatiquement au bout de *auto_timeout* secondes, si l’opérateur n’a pas lancé l’appel et qu’il est dans l’onglet campagne.
    • MANUAL: lancement en manuel
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

Notification un peu spéciale (utilisée par les alertes): Valeurs disponibles pour les principales variables:

  • duration_in_queue: depuis combien de temps
  • event:
    • alert_op: pas suffisamment d’opérateurs
    • alert_file: seuil d’appel en attente dépassé
  • id_call: identifiant de l’appel
  • id_operator: id de l’agent concerné
  • id_queue: id de la file associé à l’appel en cours
  • validity: validité de l’alerte
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.2.5 Evénement «num»

Permet d’obtenir des informations sur les appels entrants (attention pour recevoir ce type d’évènements, vous devez en faire la demande).

Exemple d’appel entrant :

				
					{"msg":{"type_dest":"GROUPE","id_call":3819,"id_num":31,"id_client":666,"service":"33820620620","caller_id_num":"33612345678"},"type_notification":"num","srv":8,"event":"start"}

Exemple de décroché (fourni uniquement si un son est joué) :

				
					{"msg":{"type_dest":"GROUPE","id_call":3819,"id_num":31,"id_client":666,"service":"33820620620","caller_id_num":"33612345678"},"type_notification":"num","srv":8,"event":"answer"}

Exemple fin d’appel :

				
					{"msg":{"type_dest":"GROUPE","id_call":3819,"id_num":31,"id_client":666,"service":"33820620620","caller_id_num":"33612345678"},"type_notification":"num","srv":8,"event":"end"}

Valeurs disponibles pour les principales variables :

  • caller_id_num: numéro de l’appelant
  • service: numéro du service
  • id_call: identifiant de l’appel
  • type_dest : correspond au dernier type de destination appelé (GROUPE, TRUNK, NO)
  • event:
    • start: arrivé d’un appel entrant
    • answer: décroché (fourni uniquement si décroché avant appel sortant)
    • end: fin d’un appel entrant
4.2.6 Evénement «input»

Permet d’obtenir des informations sur les évenments input (attention pour recevoir ce type d’évènements, vous devez en faire la demande, actuellement remonte uniquement les données de la reconnaissance vocale).

Exemple d’événement reconnaissance :

				
					{“ts”:1590431889,”elapse”:0,”event”:{“msg”:{“id_call”:40090062,”score”:97,”id”:96897,”id_client”:173778,”input”:”92″},”type_notification”:”input”,”event”:”asr”}}

Valeurs disponibles pour les principales variables :

  • id_call: identifiant de l’appel
  • event :
    • asr : reconnaisance vocale
  • score : évalution de la pertinance de la reconnaisance 0→100
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>

<title>Demo socket.io</title>
<script type="rocketlazyloadscript" src="./socket.io.js" crossorigin="anonymous" defer></script>
<script type="rocketlazyloadscript" data-minify="1" src="https://guide.axialys.com/wp-content/cache/min/1/jquery-3.2.1.min.js?ver=1666989114" crossorigin="anonymous" defer></script>
<script type="rocketlazyloadscript">window.addEventListener('DOMContentLoaded', function() {
 
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>
<script>"use strict";function wprRemoveCPCSS(){var preload_stylesheets=document.querySelectorAll('link[data-rocket-async="style"][rel="preload"]');if(preload_stylesheets&&0<preload_stylesheets.length)for(var stylesheet_index=0;stylesheet_index<preload_stylesheets.length;stylesheet_index++){var media=preload_stylesheets[stylesheet_index].getAttribute("media")||"all";if(window.matchMedia(media).matches)return void setTimeout(wprRemoveCPCSS,200)}var elem=document.getElementById("rocket-critical-css");elem&&"remove"in elem&&elem.remove()}window.addEventListener?window.addEventListener("load",wprRemoveCPCSS):window.attachEvent&&window.attachEvent("onload",wprRemoveCPCSS);</script><script>class RocketElementorAnimation{constructor(){this.deviceMode=document.createElement("span"),this.deviceMode.id="elementor-device-mode",this.deviceMode.setAttribute("class","elementor-screen-only"),document.body.appendChild(this.deviceMode)}_detectAnimations(){let t=getComputedStyle(this.deviceMode,":after").content.replace(/"/g,"");this.animationSettingKeys=this._listAnimationSettingsKeys(t),document.querySelectorAll(".elementor-invisible[data-settings]").forEach(t=>{const e=t.getBoundingClientRect();if(e.bottom>=0&&e.top<=window.innerHeight)try{this._animateElement(t)}catch(t){}})}_animateElement(t){const e=JSON.parse(t.dataset.settings),i=e._animation_delay||e.animation_delay||0,n=e[this.animationSettingKeys.find(t=>e[t])];if("none"===n)return void t.classList.remove("elementor-invisible");t.classList.remove(n),this.currentAnimation&&t.classList.remove(this.currentAnimation),this.currentAnimation=n;let s=setTimeout(()=>{t.classList.remove("elementor-invisible"),t.classList.add("animated",n),this._removeAnimationSettings(t,e)},i);window.addEventListener("rocket-startLoading",function(){clearTimeout(s)})}_listAnimationSettingsKeys(t="mobile"){const e=[""];switch(t){case"mobile":e.unshift("_mobile");case"tablet":e.unshift("_tablet");case"desktop":e.unshift("_desktop")}const i=[];return["animation","_animation"].forEach(t=>{e.forEach(e=>{i.push(t+e)})}),i}_removeAnimationSettings(t,e){this._listAnimationSettingsKeys().forEach(t=>delete e[t]),t.dataset.settings=JSON.stringify(e)}static run(){const t=new RocketElementorAnimation;requestAnimationFrame(t._detectAnimations.bind(t))}}document.addEventListener("DOMContentLoaded",RocketElementorAnimation.run);</script><noscript><link rel="stylesheet" href="https://guide.axialys.com/wp-content/cache/min/1/24713921a416b8a0eefae05c9cde7368.css" media="all" data-minify="1" /><link rel='stylesheet' id='elementor-frontend-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/custom-frontend-lite.min.css?ver=1666958935' media='all' /><link rel='stylesheet' id='elementor-post-6-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/post-6.css?ver=1666958921' media='all' /><link rel='stylesheet' id='elementor-pro-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/custom-pro-frontend-lite.min.css?ver=1666958935' media='all' /><link rel='stylesheet' id='elementor-global-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/global.css?ver=1666958936' media='all' /><link rel='stylesheet' id='elementor-post-1205-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/post-1205.css?ver=1666971934' media='all' /><link rel='stylesheet' id='elementor-post-47-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/post-47.css?ver=1666958921' media='all' /><link rel='stylesheet' id='elementor-post-209-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/post-209.css?ver=1666958922' media='all' /><link rel='stylesheet' id='google-fonts-1-css' href='https://fonts.googleapis.com/css?family=Roboto%3A100%2C100italic%2C200%2C200italic%2C300%2C300italic%2C400%2C400italic%2C500%2C500italic%2C600%2C600italic%2C700%2C700italic%2C800%2C800italic%2C900%2C900italic&#038;display=auto&#038;ver=6.1.7' media='all' /><link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans&display=swap" media="all" /><link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:300|Open+Sans:400|Open+Sans:700&display=swap" media="all" /><link rel="stylesheet" href="https://guide.axialys.com/wp-content/uploads/elementor/css/custom-widget-icon-list.min.css?ver=1666960324"><link rel='stylesheet' id='elementor-post-400-css' href='https://guide.axialys.com/wp-content/uploads/elementor/css/post-400.css?ver=1666958922' media='all' /></noscript></body>
</html>

5- Utilisation de l’API pour avoir l’ensemble des événements

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

5.1 Principe de fonctionnement

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

5.2 Authentification

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.

Pour récupérer l’ensemble des données :

				
					curl -X POST -u “<login>:<password>” -H “Content-Type: application/json” -d ‘{“user_type”:”api”}’ https://api.axialys.com/vm/token
				
			
Pour récupérer les données pour un seul opérateur : 
				
					curl -X POST -u “<login>:<password>” -H “Content-Type: application/json” -d ‘{“user_type”:”agent”,”<id_agent>”}’ https://api.axialys.com/vm/token
				
			
Pour connaitre la date d'expiration du token, cette requête retourne “expire” (date d'expiration au format yyyy-mm-ddthh-mm-ss.000000+GMT).
5.3 Evénements

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.

  • Table des matières