API Voice Management 1 Généralités L’API du Voice Management permet de configurer et de superviser le traitement des appels. 2 Formalisme Cette API s’inspire du formalisme REST. Les données sont servies au format JSON. Vous devez obtenir auprès de votre interlocuteur Axialys vos données d’authentification. 2.1 Format des requêtes Les requêtes seront de la forme https://SERVER/vm...?user=<username>&password=<password> A noter concernant le format des paramètres : les numéros de téléphone sont attendus au format E164 (c’est-à-dire code pays suivi du numéro national, par exemple 33145420000 pour un numéro parisien). les dates sont attendues au format IS0 8601. Cependant, notre système acceptera les variations les plus communes, et notamment le format AAAA-MM-DD HH:MM. 2.2 Format des réponses Les réponses sont fournies au format JSON par défaut sauf si la requête est passée depuis un navigateur, auquel cas les données sont présentées au format HTML. Pour forcer une réponse JSON, ajouter le paramètre accept=application/json . Attention, la réponse JSON est susceptible de contenir des données supplémentaires, en cas d’évolution de l’API. Ne pas en tenir compte. 3 Infos générales 3.1 Récupération des opérateurs Cette API fournit le listing des opérateurs. URL /vm/operators Méthode(s) GET Il est possible de récupérer un opérateur particulier via : URL /vm/operators/<id_operator> Méthode(s) GET Il est également possible d’utiliser la méthode POST afin de filtrer sur les données suivantes : Nom Type Oblig. Description email Email N Adresse email login Alpha-numérique N Login de connexion Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : Nom Type Oblig. Description id Y Adresse email email Email N Adresse email realname Alpha-numérique Y Nom de la personne login Alpha-numérique Y Login de connexion 3.2 Récupération de l’état courant des opérateurs Attention à ne pas faire plus d’une requête toute les 30s, à terme un contrôle sera activé. Cette API fournit le listing des opérateurs. URL /vm/operators_init Méthode(s) GET Il est possible de récupérer un opérateur particulier via : URL /vm/operators_init/<id_operator> Méthode(s) GET Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : Nom Type Oblig. Description id Y id de l operateur etat available,ringing,calling,connected,unavailable N état de l’opérateur ui_login Date N date du dernier login ui_logout Date N date du dernier logout pause Date N pause courante de l’opérateur ui_pause Date N date de la dernière pause ui_unpause Date N date de la dernière unpause groups Liste d’IDs N Liste des ID des groupes dont l’opérateur est membre 3.3 Récupération des groupes Cette API fournit le listing des groupes. URL /vm/groups Méthode(s) GET Il est possible de récupérer un groupe particulier via : URL /vm/groups/<id_groupe> Méthode(s) GET Il est également possible d’utiliser la méthode POST afin de filtrer sur les données suivantes : Nom Type Oblig. name Alpha-numérique N Nom du groupe recherché Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : Nom Type Description id Adresse email name Alpha-numérique Nom du groupe recherché 3.4 Récupération de l’historique du statut des opérateurs Cette API fournit le listing du statut des opérateurs. Attention le statut ne fournit pas le statut actuel, mais uniquement l’historique (ils sont insérés une fois que l’opérateur change d’état. Les informations d’appels peuvent également être ajoutées un peu plus tard.) URL /vm/calls/status Méthode(s) POST Les requêtes devront se faire sous la forme curl -u <username>:<password> "https://api.axialys.com/vm/calls/status" -X POST -d '{"date":"2019-04-20","date_end":"2019-05-01"}' Paramètres Nom Type Oblig. Description date Date O Date/heure de début de la période. date_end Date O Date/heure de fin de la période. id_op Numérique N ID de l’opérateur. Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : Nom Type Description id_op ID d’opérateur duration Entier Durée en secondes date Date/Heure Date de début de l’événement id_call Entier ID de l’appel infos Chaîne de caractères Infos supplémentaires type Chaîne de caractères Type de l’événement (call_in, call_out, break, login, catchup) Il n’y a pas de login_out dans Type, car avec login, on connaît la date de début et la durée. 4 Statistiques 4.1 Appels reçus (numéros) Cette API fournit des statistiques globales sur le nombre d’appels reçus au niveau télécom pour une période donnée (par défaut, la journée en cours). URL : /vm/stats/numbers_calls Méthode acceptée : GET Paramètres 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. Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : 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). Il n’est pas possible de requêter une période plus longue qu’un mois. 4.2 Appels reçus (groupes agents) Cette API fournit des statistiques sur le nombre d’appels reçus présentés aux groupes d’agents pour une période donnée (par défaut, la journée en cours). URL : /vm/stats/group_calls Méthode acceptée : GET Paramètres 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. Données retournées Les données retournées incluent les paramètres passés en entrée, ainsi que les données suivantes : 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). Il n’est pas possible de requêter une période plus longue qu’un mois. 4.3 Supervision (groupes agents) Cette API fournit des statistiques actuelles de la supervision liées à un groupe d’agents. URL : /vm/stats/group_stats Méthode acceptée : GET Format des requêtes Les requêtes devront se faire sous la forme curl -u <username>:<password> “https://api.axialys.com/vm/group_stats/<id_group>” -X GET ou wget -qO- “https://<username>:<password>@api.axialys.com/vm/group_stats/<id_group>” Paramètres Nom Type Oblig. Description group_id Entier N ID du groupe pour lequel on veut spécifiquement des données. Données retournées Les données retournées incluent le paramètre passé en entrée, ainsi que les données suivantes : Nom Type Description group_name Alpha-numérique Nom du groupe nbr_global Entier Nombre d’appels Global nbr_global_reel Entier Nombre d’appels uniques Global, dans le cas d’appels en débordement 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 nbr_perdus_reel Entier Nombre d’appels uniques Perdus, dans le cas d’appels en débordement 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 nbr_abandonne Entier Nombre d’appels abandonnés en moins de X secondes (X secondes d’attente sur le groupe). Par défaut, en moins de 5 secondes. nbr_repondu Entier Nombre d’appels répondus en moins de Y secondes (Y secondes après arrivé sur le groupe). Par défaut, en moins de 45 secondes. tps_moyen_catchup Heure Temps moyen de de Catchup La fréquence d’utilisation ne doit pas excédée à 1 requête toutes les 10 secondes. Si vous souhaitez configurer le nombre de secondes pour nbr_abandonne et pour nbr_repondu, il faut par exemple faire une requête sous la forme : curl -u <username>:<password> “https://api.axialys.com/vm/group_stats/<id_group>” -X GET -d ‘{“nbr_abandonne”:<nbr de secondes>,”nbr_repondu”:<nbr de secondes>}’ Haut de page
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 : 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. 3 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) 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 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”:{“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”:{“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”:{“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 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> <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> 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. 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 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. Haut de page
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 : 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. 3 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) 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 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”:{“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”:{“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”:{“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 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> <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> 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. 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 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.
Intégration de DESK avec le VoiceManagement En préambule, Axialys doit vous fournir l’adresse unique du voiceManagement à configurer dans votre interface DESK. Aller dans la section “admin>site setting” et cocher “phone integration”. Ensuite aller dans la section “channels>phone” et dans la partie générale activer “phone calls enable”. Puis dans la section “channels>phone” et dans la partie intégration configurer l’adresse fournie par Axialys. Attention, il faut également sélectionner l’ensemble des comptes devant avoir accès au VoiceManagement. A partir de ce point, la popin devrait être disponible dans l’interface desk nouvelle génération. Si vous n’êtes pas automatiquement logué dans l’interface, c’est que l’utilisateur n’existe pas dans l’extranet Axialys. Vous devez alors ajouter l’opérateur dans la section “VoiceManagement>Opérateurs>Ajout d’un opérateur” en vous assurant de bien renseigner la même adresse email que celle utilisée par l’agent pour se connecter sur DESK. Haut de page
API gestion des appels sortants et campagnes Cette API permet de gérer les appels à effectuer, soit en appels sortants unitaires, soit sous forme de campagne d’appels sortants. L’API permet ainsi de : Demander un nouvel appel sortant Consulter l’état d’un appel sortant Consulter l’état d’un appel sortant 1 Considérations générales L’API fonctionne suivante un paradigme de type REST, en acceptant des données sous forme de paramètres passés en GET ou en POST, et retourne des données au format JSON. 1.1 Paramètres Toutes les fonctions d’API nécessitent l’usage des paramètres suivants (en plus des paramètres spécifiques) : Nom Type Défaut Oblig. Description auth_id Alphanum 32 O Identifiant utilisateur API auth_password Alphanum 32 O Mot de passe 1.2 Retour En cas de succès, l’API répond 200 OK ainsi que les champs spécifiques à la fonction appelée. En cas d’erreur, un code retour HTTP approprié est utilisé et le message JSON contiendra les champs suivants : 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) 2 Gestion des campagnes L’usage des campagnes est optionnel : il permet d’avoir un suivi et une visualisation d’un ensemble d’appels à effectuer. L’API propose les fonctions suivantes : Créer une nouvelle campagne Modifier une campagne Consulter l’état d’une campagne (statistiques) 2.1 Créer une nouvelle campagne URL /vm/campaign Méthode(s) POST Paramètres 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) Retour Nom Type Description id_campaign Num Identifiant de la nouvelle campagne, à utiliser pour d’autres appels d’API 2.2 Modifier une campagne URL /vm/campaign/<id_campaign> Méthode(s) POST Paramètres 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) Retour 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é 2.3 Annuler une campagne URL /vm/campaign/<id_campaign>/cancel Méthode(s) POST Paramètres Aucun Retour 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é 2.4 Consulter l’état d’une campagne URL /vm/campaign/<id_campaign> Méthode(s) GET Paramètres Aucun Retour 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é total_calls_count Num 8 Nombre total d’appels à passer ok_status_count Num 8 Nombre d’appels réussis ko_status_count Num 8 Nombre d’appels en échec pending_status_count Num 8 Nombre d’appels encore à effectuer 3 Gestion des appels sortants 3.1 Demander un nouvel appel sortant URL /vm/outbound_call Méthode(s) POST Format des requêtes Les requêtes devront se faire sous la forme curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X POST -d '{"dest_number":<numéro>,"id_agent":<id_agent>}' Paramètres 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 100 N Priorité d’appel; par défaut 100; 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 Id_msg_op Num N Identifiant du message sonore à jouer à l’opérateur Il est possible d’assigner des appels sortants à un agent d’un groupe si “id_agent” et “id_group” sont renseignés dans la même requête. Retour Nom Type Description id_out_call Num Un à plusieurs identifiants de numéros de destinataires en fonction de s’il s’agit d’une campagne ou d’un appel sortant unitaire, séparés par des virgules 3.2 Consulter l’état d’un appel sortant URL /vm/outbound_call/<id_out_call> Méthode(s) GET Paramètres Aucun Retour Les champs identiques à ceux passés lors de la création de l’appel sont retournés, avec en plus : 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 3.3 Supprimer un ou des appels sortants URL /vm/outbound_call Méthode(s) DELETE Seul les demandes dans l’état PENDING sont impactées par cette méthode Format des requêtes Les requêtes devront se faire sous la forme curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X DELETE -d '{"dest_number":<numéro>,"id_agent":<id_agent>}' Paramètres 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 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 100 N Priorité d’appel; par défaut 100; 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 id_agent Num 10 N L’agent qui va devoir faire l’appel (obligatoire si un groupe n’est pas choisi) id_group Num 10 N Le groupe d’agents qui va devoir faire l’appel (obligatoire si un opérateur n’est pas choisi) Retour Nombre d’appels impactés. 3.4 Modifier un ou des appels sortants URL /vm/outbound_call Méthode(s) PUT Seul les demandes dans l’état PENDING sont impactées par cette méthode Format des requêtes Les requêtes devront se faire sous la forme curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X PUT -d '{"dest_number":<numéro>,"id_agent":<id_agent>}' Paramètres 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 100 N Priorité d’appel; par défaut 100; 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 60 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 Id_msg_op Num N Identifiant du message sonore à jouer à l’opérateur Retour Nombre d’appels impactés. Haut de page
API historique des appels Cette API permet de récupérer l’historique des appels entrants et sortants, en deux méthodes. 1 Considérations générales L’API fonctionne suivante un paradigme de type REST, en acceptant des données sous forme de paramètres passés en GET ou en POST, et retourne des données au format JSON. 1.1 Paramètres Toutes les fonctions d’API nécessitent l’usage des paramètres de connexion suivants : Nom Type Défaut Oblig. Description login Alphanum 32 O Identifiant utilisateur API password Alphanum 32 O Mot de passe Et des paramètres servant de filtre pour l’extraction des données : Nom Type Défaut 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 1.2 Historique des appels entrants URL /vm/calls/in Méthode(s) POST Format de la requête La requête devra se faire sous la forme : curl “https://api.axialys.com/vm/calls/in” -u <login>:<password> -H “Content-Type: application/json” -d ‘{“date”:”<YYYY-MM-DD>”, “date_end”:”<YYYY-MM-DD>”, “service_number”:”<e164>”, “caller_number”:”<e164>”}’ -X POST Retour 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 duration_svi Numérique Durée passée sur le SVI avant d’entrer dans une file d’attente d’un groupe duration_hold Numérique Durée pendant laquelle un appel a été mis en attente par l’opérateur pendant l’appel duration_comm Numérique Durée de communication entre l’appelant et l’opérateur duration_wait Numérique Durée d’attente de l’appelant avant le décroché de l’appel 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 id_op Numérique Identifiant de l’opérateur ayant reçu l’appel NB : “op_name”, et “rub_name” sont mises à jour 2h après, il faut appeler la méthode au moins 2 heures après l’heure de fermeture du service. 1.3 Historique des appels sortants URL /vm/calls/out Méthode(s) POST Format de la requête La requête devra se faire sous la forme : curl “https://api.axialys.com/vm/calls/out” -u <login>:<pass> -H “Content-Type: application/json” -d ‘{“date”:”<YYYY-MM-DD>, ” date_end “:”<YYYY-MM-DD>”, “service_number”:”<e164>”, “called_number”:”<e164>” }’ -X POST Retour 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 id_op Numérique Identifiant de l’opérateur ayant reçu l’appel (N.B. : à partir du 19/06/20) L’id_appel d’un appel sortant est précédé d’un “-”. 1.4 Inventaires des statuts des appels Commun aux deux types : Nom Description ANSWER répondu BUSY occupé NOANSWER non répondu UNKNOWN inconnu CANCEL annulé CONGESTION congestion CHANUNAVAIL channel indisponible Spécifique aux appels entrants : Nom Description NO pas d’aboutement CALLBACK callback VOICEMAIL boite vocale 1.5 Historique des appels dans les groupes URL /vm/calls/groups Méthode(s) POST Format de la requête La requête devra se faire sous la forme : curl “https://api.axialys.com/vm/calls/groups” -u <login>:<password> -H “Content-Type: application/json” -d ‘{“date”:”<YYYY-MM-DD>”, “date_end”:”<YYYY-MM-DD>”, “service_number”:”<e164>”, “caller_number”:”<e164>”}’ -X POST Retour 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 date_in Date Date d’entrée dans le groupe, au format ISO 8601 date_out Date Date de sortie du groupe, au format ISO 8601 date_answer Date Date appel répondu, au format ISO 8601 duration Numérique Durée de l’appel, en seconde group_name Alphanum Nom du groupe ayant reçu l’appel op_name Alphanum Nom de l’opérateur ayant reçu l’appel 1.6 Historique des appels dans les rubriques URL /vm/calls/rubriques Méthode(s) POST Format de la requête La requête devra se faire sous la forme : curl “https://api.axialys.com/vm/calls/rubriques” -u <login>:<password> -H “Content-Type: application/json” -d ‘{“date”:”<YYYY-MM-DD>”, “date_end”:”<YYYY-MM-DD>”, “service_number”:”<e164>”, “caller_number”:”<e164>”}’ -X POST Retour 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 date_in Date Date d’entrée dans la rubrique, au format ISO 8601 duration Numérique Durée de l’appel, en seconde rub_name Alphanum Nom de la rubrique ayant reçu l’appel Haut de page
Intégration du VM dans un CRM Voici les méthodes pouvant être utiliser pour l’intégration du VM dans un CRM. 1 SSO 1.1 Connexion opérateur A la connexion de l’utilisateur, il faut récupérer un token via la méthode : curl -X POST -u "<login>:<pass>" -H "Content-Type: application/ json" -d '{"id_agent":<id_agent>, "withUuid": true}' https://api.axialys.com/vm/token ou anciennement curl -X POST -u “<login>:<pass>” -H “Content-Type: application/json” -d ‘{“ip”:”<ip>”,”id_agent”:<id_agent>}’ https://api.axialys.com/vm/token possibilité d’utiliser l’email de l’opérateur : curl -X POST -u "<login>:<pass>" -H "Content-Type: application/json" -d ' {"email":<email>, "user_type":"agent", "withUuid": true}' https://api.axialys.com/vm/token Vous avez la possibilité d’ajouter la variable keep pour tenter de garder tout le temps le même token : curl -X POST -u "<login>:<pass>" -H "Content-Type: application/json" -d '{"ip":"<ip>", "id_agent":<id_agent>, "withUuid": true, "keep":1}' https://api.axialys.com/vm/token Attention : l’option “withUuid”: true permet d’avoir un identifiant unique et aléatoire. Seul le format json est supporté. Puis il faut appeler le popin dans une iframe avec l’url : https://voice-management.axialys.com/operateurs/index.htm?token_session=<token> 1.2 Déconnexion A la déconnexion de l’utilisateur, il faut invalider le token via la méthode : curl -X DELETE -u "<login>:<pass>" -H "Content-Type: application/json" -d '{"ip":"<ip>","id_agent":<id_agent>}' https://api.axialys.com/vm/token/<token> 1.3 Connexion supervision A la connexion de l’utilisateur, il faut récupérer un token via la méthode : curl -X POST -u “<login>:<pass>” -H “Content-Type: application/json” -d ‘{“ip”:”<ip>”,”id_admin”:<id_admin>, “withUuid”: true}’ https://api.axialys.com/vm/token possibilité d’utiliser l’email du superviseur : curl -X POST -u “<login>:<pass>” -H “Content-Type: application/json” -d ‘{“ip”:”<ip>”,”email”:<email>, “user_type”:”admin”, “withUuid”: true}’ https://api.axialys.com/vm/token Seul le format json est supporté. Puis il faut appeler la page via: https://voice-management.axialys.com/superviseur/index.htm?token_session=<token> 1.4 Déconnexion A la déconnexion de l’utilisateur, il faut invalider le token via la méthode : curl -X DELETE -u “<login>:<pass>” -H “Content-Type: application/json” -d ‘{“ip”:”<ip>”,”id_agent”:<id_agent>}’ https://api.axialys.com/vm/token/<token> 2 Click-to-call Il vous suffit au clic du numéro de téléphone, d’appeler l’url de notre bandeau en ajoutant une variable fiche_num avec le numéro souhaité permettant ainsi un pré-enregistrement du numéro de téléphone dans le bandeau. Exemple pour afficher le 33618220000, il faut appeler l’url : https://voice-management.axialys.com/operateurs/index.htm?fiche_num=33618220000&token_session=<token> 3 Remontée de fiche vers votre CRM Si votre CRM (basé sur le web) n’est pas nativement supporté par notre solution, néanmoins vous pouvez tout à fait le connecter à notre plate-forme et déclencher l’ouverture d’une fiche client en fonction de l’appel entrant. 3.1 Principe de fonctionnement Le principe est le suivant : vous mettez en place une URL dans votre système qui sera dédiée à l’ouverture des fiches client cette URL est configurée dans notre système lors d’un appel entrant, une nouvelle page est ouverte vers cette URL à laquelle on passe en paramètre un certain nombre de variables, permettant à cette page d’afficher la fiche pertinente 3.2 Paramètres passées La page appelée est susceptible de recevoir au moins les variables suivantes en paramètre (query string) : 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 D’autres paramètres sont susceptibles d’être passés, suite à certaines actions éventuelles dans le SVI (numéro de commande par exemple). 4 Nouvelle API VoiceManagement Vous pouvez interagir avec l’UI de l’opérateur si cette dernière est intégrée via une iframe, en incluant un JS sur votre site, qui va se charger de la communication avec l’iframe et les problèmes de cross-domain. Vous disposez alors d’un objet “crm” auquel vous pourrez enregistrer des fonctions de callback qui seront alors appelées en cas d’événement accompagné d’un certain nombre de paramètres associés. Ainsi que des méthodes d’actions comme pour pré-renseigner le champ numéro. L’iframe doit être appelée avec les 2 paramètres suivants: engine : standard version : 1 Le JS à inclure est le suivant : cnx.js Un exemple d’implémentation est fourni ci-dessous : index.htm 4.1 Authentification Demander à la popup de se connecter en utilisant le token fourni crm.login(<id_token>) Demander à la popup de se connecter en utilisant les logins/password fournis crm.login_credential(<login>, <password>) Masquer le bouton de déconnexion crm.hide_logout() Configurer une fonction de callback qui sera appelée pour indiquer que le token n’est plus valide crm.set_auth_invalid() 4.2 Notifications Permet de définir une fonction de callback qui sera rappelée avec un tableau associatif avec l’ensemble des variables disponibles (id_session, e164_in, id_call, caller_id_num, id_op, id_groupe, wait (temps d’attente)) crm.set_notif_in(<fct>) Définir une fonction de callback qui sera rappelée avec un tableau associatif avec l’ensemble des variables disponibles (id_session, e164_out, id_call, caller_id_num, id_op, id_groupe) crm.set_notif_out(<fct>) Configurer une fonction de callback qui sera appelée à chaque modification de statut de l’opérateur crm.set_notif_status() Configurer une fonction de callback qui sera appelée à la fin d’un appel crm.set_notif_endCall() Configurer une fonction de callback qui sera appelée à la fin d’un appel manqué crm.set_notif_missedCall() 4.3 Autres interactions Pré-renseigner le numéro pour effectuer un clic2call, “ticket_id” référence utilisé uniquement pour Zendesk (permet de relier un ticket et un appel) crm.call(<phone>, <ticket_id>) 4.4 OmniCanal Pour pouvoir se mettre en ligne/pause/déconnecté avec un crm , trois méthodes sont disponibles dans un objet set_omnichannel crm.set_omnichannel({ subscribe: <subscribe_fst>, unsubscribe: <unsubscribe_fst>, publish: <publish_fst> }) ; L’enregistrement d’un callback pour s’abonner. Le callback doit fournir de quoi traiter les événements crm.subscribe(<fct>) Le désabonnement crm.unsubscribe() L’envoi de messages au format JSON crm.publish({ status: “online|busy| }) Haut de page