FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)

Voice Management notifications API

5 Introduction

This API enables you to get a real-time feed of events for all aspects of Voice Management’s operation such as agents, queues, routes etc. It can be used for various purposes, including the production of supervision dashboards.

It is based on the Socket.IO protocol

6 Operating principle

Using the API requires two steps:

  1. a first step authentication, in the form of a normal HTTP request
  2. the actual use so to speak, via the Socket.IO library, using the authentication created in the previous point.

7 Authentification

Before being able to log in to our notification server, an authentication token must be obtained which will then be valid for 2 hours. The request must be sent from the machine where the notififications processing will be handled. It is verified via the token and the IP.

Authentication requires the use of a “supervisor” login/password.

You must therefore make a POST request by configuring a JSON header with the credentials to obtain the token which will be used for authentification with the notification server.

Include the following data in the JSON:

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

Example of authentication request with CURL:

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

This request returns all the information needed for receiving notifications and configuring groups and agents in a JSON object.

The main information you should note is:

  • ops (id, name, groups[])
  • groupes (id, name)
  • trunks (id, name)
  • pauses (id, value)
  • target (supervisor' ID)
  • id_session

The last two parameters are the supervisor account ID (target) and the token (id_session) that is needed for authentication, see below.

8 Notification feed

8.1 Log in

The notification feed uses the Socket.IO Javascript library protocol. The examples below are in Javascript, but any library compatible with this protocol should work.

Once authentication has taken place and you have obtained the authentication token, you can log in to the notification server to receive events in real time.

We recommend setting a callback on events of the update type, and then requesting the feed to start via an init type message.

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

8.2 Events

The data is sent in the form of a JSON object, with the name of the event which will always be “update” and a structure in the following form:

  • cpt: event number
  • elapse: time since the event
  • event:
    • event: insert_call
    • type_notification: queue |operator |UI |trunk
  • ts: timestamp to which the event was sent

There are 5 types of events as listed below:

  • operator: relates to an agent’s comm status.
  • UI: relates to the agent’s interface status, login/breaks, etc.
  • PUSHCALL: A request has been sent to ask an agent to make an outgoing call.
  • queue: information about an agent-type queue.
  • trunk: information about a routing type queue.

8.2.1 Operator event

Used to obtain information about an agent’s status:

Example:

{“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”}

Values available for the main variables:

  • call_duration: duration of the call
  • caller_id_num: caller's number
  • id_call: call id
  • id_operator: id of the agent involved
  • id_queue: queue id associated with the current call
  • rec: call likely to be recorded
  • catchup: catchup time after call (filled in only at the end of a call)
  • status
    • available: agent available
    • ringing: ringing agent
    • calling: call made
    • connected: call in progress
    • unavailable: unknown status
    • transfert_start: start of a call transfer
    • transfert_end: end of a transfer

8.2.2 UI event

Enables you to get information about login/logout/breaks or any other type of information related to the agent interface.

Example login:

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

Example of a break: {“msg”: {“supp”: “user1”, “id_operator”: 1, “id_client”: 1}, “type_notification”: “UI”, “event”: “pause”}

Values available for the main variables:

  • event:
    • login: agent login
    • logout: agent logout
    • pause: entering a break type event
    • unpause: exit from break
    • push: push to operator interface
    • push_cancel: attempt to cancel the various events pushed towards the operator
  • id_operator: ID of the agent in question
  • supp: additional information, specifically identifying the type of break

Specific variables contained in “msg” about the fact that events are being pushed towards the client interface (push).

  • retry_timeout: duration between 2 attempts
  • auto_timeout: timeout, after which a call will start if the operator has not already started it and if there’s an “AUTO” type request in place
  • vars: variables
  • ring_timeout: ring time
  • expire: allocation expiration
  • unassign_timeout: timeout for non-allocation of call
  • retries: number of attempts remaining
  • priority: call priority (1 to 100)
  • e164: nnumber for getting in contact with the operator
  • type:
    • AUTO: launch the call automatically after *auto_timeout* seconds, if the operator has not started the call and it is in the campaign tab.
    • MANUAL: manual launch

8.2.3 “Queue” event

Enables you to obtain information about the login/logout or any other type of information linked to the interface, of the user on a break type.

Example of an incoming call:

{"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"}

Example of contact:

{"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"}

Example of queue exit:

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

Values available for the main variables:

  • call_duration: duration of the call
  • caller_id_num: caller's number
  • duration_in_queue: waiting time in the queue
  • event:
    • connect_call: contact
    • delete_call: call ended
    • insert_call: incoming call in queue
  • id_call: call id
  • id_operator: id of the agent involved
  • id_queue: queue id associated with the current call
  • rec: recorded call
  • statut
    • available: agent available
    • ringing: ringing agent
    • calling: call made
    • connected: call in progress
    • unavailable: unknown status

A rather special notification (used by alerts): Values available for the main variables:

  • duration_in_queue: for how long
  • event:
    • alert_op: not enough operators
    • alert_file: call waiting threshold exceeded
  • id_call: call id
  • id_operator: id of the agent involved
  • id_queue: queue id associated with the current call
  • validity: alert validity

8.2.4 “Trunk” event

Enables you to obtain information on routing type calls

Example of adding a call:

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

Example of contact:

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

Example of end of call:

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

Values available for the main variables:

  • caller_id_num: caller's number
  • call_duration: duration of the call
  • id_call: call id
  • id_trunk: routing account ID
  • event:
    • insert_call: addition of a call to a queue
    • connect_call: contact
    • delete_call: end of call

8.2.5 «num» event

Allows you to obtain information on incoming call (note: to receive these types of events, you must submit a request; currently voice recognition data only is uploaded).

Example of incoming call:

{“msg”:{“id_call”:3819,”id_num”:31,”id_client”:666,”service”:”33820620620″,”caller_id_num”:”33612345678″},”type_notification”:”num”,”srv”:8,”event”:”start”}

Example of off-hook call (if a sound is played) :

{“msg”:{“id_call”:3819,”id_num”:31,”id_client”:666,”service”:”33820620620″,”caller_id_num”:”33612345678″},”type_notification”:”num”,”srv”:8,”event”:”answer”}

Example of end call :

{“msg”:{“id_call”:3819,”id_num”:31,”id_client”:666,”service”:”33820620620″,”caller_id_num”:”33612345678″},”type_notification”:”num”,”srv”:8,”event”:”end”}

Available values for the main variables:

  • caller_id_num: caller's number
  • service: service's number
  • id_call: call id
  • event:
    • start: start incoming call
    • answer: answer
    • end: end incoming call

8.2.6 "Input" event

Allows you to obtain information on input events (note: to receive these types of events, you must submit a request; currently voice recognition data only is uploaded).

Example of a recognition event:

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

Available values for the main variables:

  • id_call : Call identifier
  • Event
    • asr : voice recognition
    • score: evaluation of recognition accuracy 0→100

8.2.7 Example with a complete message

Below is an example of a complete message such as the JSON that will be received.

Example:

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

8.3 Example call

Prior to this, you have to generate a token and add the supervisor ID ([target]) to the “id_sup” variable and the session ID ([id_session]) to the “id_session” variable.

<!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>

9 Using the API to get all the events

You can use the API differently to get all the events, from the presentation of the call, including before off-hook, during the ringing period or the pre-off hook message

9.1 Operation

Using the API also requires the two steps described above, namely authentication by generating a token, then calling the API, using the previously created token.

9.2 Authentication

Before being able to log in to our notification server, an authentication token must be obtained which will then be valid for 2 hours. The request must be sent from the machine where the notififications processing will be handled. Verification is achieved via the token and the IP.

Authentication requires the use of a login/password that corresponds to your API account (if you do not have one, please request one).

You must therefore make a POST request by configuring a JSON header with the credentials to obtain the token which will be used for authentification with the notification server.

In the following form, with CURL:

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

9.3 Events

Here is an example of how to use it

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

To test it, you just need to replace id_client with the one you received and id_session with the one sent to you through the token generation so that you can scroll through all the events in your account.