API Voice Management

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 :

une première étape d’authentification, sous forme de requête HTTP normale
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>

Nom	Type	Oblig.	Description
from_date	Date/Heure	N	Date/heure de début de la période. Par défaut, aujourd’hui à 00:00
to_date	Date/Heure	N	Date/heure de fin de la période. Par défaut, maintenant.
dest_number	Alphanum	N	Numéro pour lequel on veut spécifiquement des données. Ce paramètre peut-être indiqué plusieurs fois; dans ce cas les données de tous les numéros indiqués sont cumulées.
include_realtime		N	Lorsque ce paramètre est positionné, des données d’état “temps réel” sur les appels en cours sont incluses.

Nom	Type	Oblig.	Description
total_duration	Entier	O	Durée totale des appels reçus en secondes.
calls_count	Entier	O	Nombre total d’appels reçus.
agent_connected_calls_count	Entier	O	Nombre d’appels ayant donné lieu à une connexion effective vers un agent.
active_calls	Entier	N	Nombre d’appels en cours sur le ou les numéros concernés par la requête (si include_realtime).
in_conversation_calls	Entier	N	Nombre d’appels en conversation sur le ou les numéros concernés par la requête (si include_realtime).
oldest_call_since	Date/Time	N	Horodatage du début de l’appel le plus ancien en cours (si include_realtime).
oldest_in_conversation_call_since	Date/Time	N	Horodatage du début de l’appel en conversation le plus ancien en cours (si include_realtime).

Nom	Type	Oblig.	Description
from_date	Date/Heure	N	Date/heure de début de la période. Par défaut, aujourd’hui à 00:00
to_date	Date/Heure	N	Date/heure de fin de la période. Par défaut, maintenant.
group_id	Numérique	N	ID du groupe pour lequel on veut spécifiquement des données. Ce paramètre peut-être indiqué plusieurs fois; dans ce cas les données de tous les groupes indiqués sont cumulées.
include_realtime		N	Lorsque ce paramètre est positionné, des données d’état “temps réel” sur les appels en cours sont incluses.

Nom	Type	Oblig.	Description
total_duration	Entier	O	Durée totale des appels reçus par les agents en secondes.
calls_count	Entier	O	Nombre total d’appels reçus par les agents.
agent_connected_calls_count	Entier	O	Nombre d’appels décrochés par un agent.
active_calls	Entier	N	Nombre d’appels en cours sur le ou les groupes concernés par la requête (si include_realtime).
oldest_call_connected_since	Date/Time	N	Horodatage du début de la plus ancienne conversation avec un agent en cours (si include_realtime).
oldest_call_waiting_since	Date/Time	N	Horodatage du début de l’attente de l’appel le plus ancien en cours (si include_realtime).

Nom	Type	Description
group_name	Alpha-numérique	Nom du groupe
nbr_global	Entier	Nombre d’appels Global
nbr_escalades	Entier	Nombre d’appels Escaladés
pourc_decroche	Entier	Pourcentage d’appels Décrochés
nbr_comm	Entier	Nombre d’appels En communication
nbr_attente	Entier	Nombre d’appels En attente
nbr_perdus	Entier	Nombre d’appels Perdus
tps_max_attente	Heure	Temps max d’attente
tps_moyen_attente	Heure	Temps moyen d’attente
tps_moyen_comm	Heure	Temps moyen de communication
tps_moyen_abandon	Heure	Temps moyen d’abandon
nbr_appels_attente_moins1m	Entier	Nombre de personnes en attente de moins de 1 minute
nbr_appels_attente_1a3m	Entier	Nombre de personnes en attente entre 1 et 3 minutes
nbr_appels_attente_3mplus	Entier	Nombre de personnes en attente de plus de 3 minutes

Nom	Type	Défaut	Oblig.	Description
auth_id	Alphanum 32		O	Identifiant utilisateur API
auth_password	Alphanum 32		O	Mot de passe

Nom	Type	Description
status	Num	Code de retour HTTP
err_code	Alphanum 16	OK en cas de succès, ou un code d’erreur spécifique, par exemple INVALID_AUTH
err_msg	Alphanum	Message d’erreur (lisible par un humain)

Nom	Type	Défaut	Oblig.	Description
name	Alphanum 32		O	Nom de la campagne à créer
record	Bool	0	N	Activation de l’enregistrement de tous les appels pour cette campagne. NB: même si cette valeur est à 0, l’enregistrement peut être actif pour d’autres raisons (par exemple, configuré sur un agent)

Nom	Type	Défaut	Oblig.	Description
name	Alphanum 32		N	Nouveau nom de la campagne
record	Bool	0	N	Activation de l’enregistrement de tous les appels pour cette campagne. NB: même si cette valeur est à 0, l’enregistrement peut être actif pour d’autres raisons (par exemple, configuré sur un agent)
pause	Bool		N	Dés/activation de la mise en pause de la campagne (inchangé si paramètre absent)

Nom	Type	Description
id_campaign	Num	Identifiant de la campagne
name	Alphanum 32	Nom de la campagne
pause	Bool	Indication de pause de la campagne
record	Bool	Indication de l’enregistrement activé

Nom	Type	Défaut	Oblig.	Description
id_campaign	Num		N	Identifiant de la campagne de laquelle l’appel fait partie
type	AUTO/MANUAL	MANUAL	N	Type pour passer l’appel sortant. AUTO : l’appel est automatiquement lancé dès qu’un agent est libre, MANUAL l’agent doit valider le lancement de l’appel
id_agent	Num 10		O/N	L’agent qui va devoir faire l’appel (obligatoire si un groupe n’est pas choisi)
id_group	Num 10		O/N	Le groupe d’agents qui va devoir faire l’appel (obligatoire si un opérateur n’est pas choisi)
dest_number	Alphanum 1024		O	Un ou plusieurs numéros de destinataires en fonction de s’il s’agit d’une campagne ou d’un appel sortant unitaire (sous le format E.164 sans +, séparés par des virgules). Ex: 33170200200,33634123452
priority	Num 3	N	N	Priorité d’appel; par défaut 10; si la valeur est inférieure, alors cet appel sera prioritaire; si elle est supérieure, il sera non prioritaire
variables	Alphanum 255		N	Variables spécifiques à l’appel, présentées dans la popup et utulisables pour le suivi statistiques. Format de type structure JSON. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeout	Num 4	30	N	Temps max de sonnerie, en seconde
retries	Num 4	3	N	Nombre maximum de tentative de rappel en cas d’échec
retry_timeout	Num 4	300	N	Temps (minimal) entre chaque nouvelle tentative, en secondes
auto_timeout	Num 4	0	N	Temps (minimal) avant le déclenchement automatique de l’appel, en secondes
unassign_timeout	Num 4	60	N	Temps maximum qu’a l’opérateur pour passer l’appel avant attribution à un autre opérateur, en secondes
start_from_date	Date/Heure	Maintenant	N	Date de début pour passer un ou plusieurs appels, sous forme ISO8601. Ex: 2016-11-05T09:00
end_before_date	Date/Heure	Aucun	N	Date de fin pour passer un ou plusieurs appels, sous forme ISO8601
start_from_hour	Heure		N	Heure (quotidienne) de début pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS
end_before_hour	Heure		N	Heure (quotidienne) de fin pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS

Nom	Type	Description
date_submitted	Date/Heure	Date de création, sous forme ISO8601
alloc_to_id_agent	Num	Identifiant de l’agent ayant passé l’appel
status	PENDING/ASSIGNED/DIALING/CONNECTED/SUCCESS/FAILURE	Statut de l’appel
call_date	Date/Heure	Date de l’appel passé (ou de la dernière tentative), sous forme ISO8601
answered_duration	Num	Durée de l’appel (en secondes)
failure_reason	Alphanum 16	Raison de l’échec

Nom	Type	Défaut	Oblig.	Description
login	Alphanum 32		O	Identifiant utilisateur API
password	Alphanum 32		O	Mot de passe

Nom	Type	Oblig.	Description
date	YYYY-MM-DD	O	Date de début ou date du jour demandé
date_end	YYYY-MM-DD	N	Date de fin, max 1 mois par rapport à la date de début
service_number	Numérique	N	Numéro de service, au format e164
caller_number	Numérique	N	Numéro de l’appelant, au format e164

Nom	Type	Description
id_appel	Numérique	identifiant de l’appel
date	Date	Date, au format ISO 8601
service_number	Numérique	Numéro du service, au format e164
caller_number	Numérique	Numéro de l’appelant, au format e164
cp	Numérique	Code postal de l’appelant
post_appel	Numérique	Durée pause, en seconde
duration_ring	Numérique	Durée de sonnerie, en seconde
duration	Numérique	Durée de l’appel, en seconde
status	Alphanum	Statut de l’appel sortant
group_name	Alphanum	Nom du groupe ayant reçu l’appel
op_name	Alphanum	Nom de l’opérateur ayant reçu l’appel
rub_name	Alphanum	Nom de la rubrique ayant reçu l’appel

URL	/vm/campaign
Méthode(s)	POST

URL	/vm/campaign/<id_campaign>
Méthode(s)	POST

URL	/vm/campaign/<id_campaign>/cancel
Méthode(s)	POST

URL	/vm/campaign/<id_campaign>
Méthode(s)	GET

Nom	Description
ANSWER	répondu
BUSY	occupé
NOANSWER	non répondu
UNKNOWN	inconnu
CANCEL	annulé
CONGESTION	congestion
CHANUNAVAIL	channel indisponible

Paramètre	Description
id_session	Token identifiant la connexion de l’agent au Voice Management
e164_in	Numéro appelé, format E164. Ex: 33170200200
id_call	Identifiant unique de l’appel sur la plate-forme
caller_id_num	Numéro d’appelant, format E164. Ex: 33635438729
action	Vaut in pour un appel entrant
id_op	id de l’opérateur
id_group	id du groupe
wait	temps d’attente

API Voice Management