Workflow description for external CRM API

API CRM delivers only the notification event for an incoming call or when the phone is used to start an outbound call. The management for this event and the integration with your CRM application must be done by you. If you wish, we can provide service for implementing this feature on your CRM applications.

For creating a connection, you will need the unique id of the connected agent. This ID is displayed in the External CRM field, placed inside the PHONE container.

External CRM field
External CRM field

An API CRM session will follow the next steps:

Establish the connection

The connection with the server runs using web-sockets protocol. The messages are formatted using the JSON standard. The requests will be send to our url: wss://client.voipit.ro:14327.

Authentication

After the connection has been established, the CRM application must send an authentication message to the Accolades server.

{"type":"authRequest", "idCrm":"f8cb549544"}

The message has two parameters:

"type":"authRequest"
defines the type of package: authRequest (authentication requests);
"idCrm":"f8cb549544"
defines the ID of the agent that will be notified.

Authentication answer

Following the authentication request, the server will send an answer with the connection status.

{"type":"authSucces", "version":"X.X.X"}

{"type":"authFailed", "reason":"REASON"}

"authSucces" message is send when the connection has been accepted by the server. The package also contains the current version of the API - "version"

"authFailed" message is send when the server denies the authentication request, also providing a reason:

ID_NOT_FOUND
the ID was not found on any connected agent;
IP_MISSMATCH
the agent IP is different from the IP that requested the API;
CONNECTION_EXISTS
the agent already has an API connection running.

Additional configuration data

While the call center is running Accolades uses 3 types of entities:

the phone
either a physical device or a software application;
the account
the group that contains all the phone inside the call center (and probably inside the company that owns the call center);
the agent
the person that uses the phone.

Using the Accolades interface, each of these entities can have a text, up to 2000 characters in length, that can be used for storing configuration settings (please check the API tab from the info page for each of this type on entities). You can use any type of format for storing data: JSON, XML, CSV or any other structure.

To get the additional data for each entity, the CRM application has to send to the Accolades server the following package:

{"type":"configuration"}

The Accolades server will respond with data about the account, phone and agent, with a package structured as it follows:

{
  "type": "configuration",
  "account": {
    "id": "15",
    "data": "INFO_ACCOUNT"
  },
  "phone": {
    "id": "27",
    "data": "INFO_PHONE"
  },
  "agent": {
    "id": "321",
    "data": "INFO_AGENT"
  },
}

The package contains the following properties:

type
the type of this package: configuration;
account, phone, agent
a set of properties for each of the 3 entities described above: account, phone and call center agent;
id
the unique numerical ID for the described entity;
data
the data (text) stored by Accolades for that entity.

The id for the entities is unique at an entity level. That means that it is impossible to have 2 different agents, both with the id 15, but it is possible to have an agent with the id 15 and an account with the id 15.

Call events sent by server

If the connection has been authenticated, the server will send a message to your CRM application when a call is sent to the agent. The message has the following structure:

{
  "type": "incomingCall",
  "phoneNumber":"0211234567",
  "uniqueId":"1608743891.1344"
  "callCenter":"yes"
}

The message has three parameters:

type
defines the message type: incomingCall or outgoingCall;
phoneNumber
the phone number for the call;
uniqueId
the unique ID of the call, as a number.number value;
callCenter
(yes or no) if the parameter is set to "yes" then the call was processed using the call-center module (an inbound call from a waiting queue or an outbound call from an outgoing campaign), if the parameter is set to "no" the a direct call is being processed (the device has been directly called or someone has dialled a number using the device).

Version check

The current API is at version 1.1.0. The versioning system uses the Sequence-based identifiers (major.minor.patch), including the compatibility between versions standard.

To check the version running on the server, the client has to send a request package like this:

{"type":"version"}

Based on that request, a package will be received from the server:

{"type":"version", "value":"1.1.0"}

Closing the connection

If the Accolade server decides to terminate the connection, for any reason (for example, if the agent has closed the web-interface) then the server will send a message that notifies the closure, just before the connection is terminated:

{"type":"connectionClosed"}