Analytics Realtime Data API
Async API Definition
Analytics Realtime Data 0.1.1 documentation
Analytics Realtime Data provides a mechanism for third-party clients to subscribe for Analytics Realtime Data. Measures for an Event Source and Measure Producer will be produced as Realtime Data onto an outgoing websocket.
Overview
Analytics Realtime Data hosts a websocket endpoint which allow clients to consume realtime data that has been produced by Analytics.
Connecting to the WebSocket
In order to receive data from the websocket the client must first subscribe as a consumer via Notification API.
Creating a Subscription
The Notification API provides REST API's to add, update or delete subscriptions. Clients that make a subscription request to Notification API to receive a subscription response containing the websocket endpoint. Once a subscription response has been obtained the client can subscribe to the websocket endpoint for Realtime data.
Realtime Data Filtering and Processing
Once the client is connected to the WebSocket they will receive initialization messages containing a snapshot of the most up to date values for all the measures calculated for a Measure Producer.
Once the initialization process is complete, the client will start receiving live messages.
Table of Contents
Servers
production Server
URL | Protocol | Description |
---|---|---|
wss://{server}:{port}/ws/notification | wss | After connection to the websocket a new session is created. |
URL Variables
Name | Default value | Possible values | Description |
---|---|---|---|
server | HOST-REGION.avayacloud.com | Any | - |
port | 443 | 443 | Secure connection (TLS) is available through port 443. |
Security Requirements
Type | In | Name | Scheme | Format | Description |
---|---|---|---|---|---|
oauth2 | - | - | - | - | - |
Channels
/v1/analytics/realtime Channel
publish
Operation
publish
OperationPing Server.
Accepts one of the following messages:
Message ping
ping
Client can ping server to determine whether connection is alive, server responds with pong. The ping is also used to keep the websocket connection alive, by keep sending ping messages every pingInterval time to the server. The Client calls the ping method on the websocket framework library API for whichever programming language that is used by the client to establish the websocket.
Tags
- Heartbeat
Message authentication
authentication
The first message the client should send to server after establish the connection must be an authentication message.
Payload
Name | Type | Description | Accepted values |
---|---|---|---|
event (required) | string | authentication - A constant parameter. | Any |
subscriptionId | string | The unique 36 character internal id that represents the subscription. | Any |
token (required) | string | OAuth2 token | Any |
Examples of payload
authenticationMessage
Example of an authentication message to server.
{
"event": "authentication",
"subscriptionId": "fdbec917-e76e-4645-8120-4eac46f29488",
"token": "eyJqa3UiOiJodHRwczpcL1wvYXBpLWRldi5hdmF5YS5jb21cL2FjY2Vzc3Rva2VuXC9qd2tz"
}
Tags
- Authentication
subscribe
Operation
subscribe
OperationOutgoing Realtime Data
Accepts one of the following messages:
Message Event data
Event data
Payload
Name | Type | Description | Accepted values |
---|---|---|---|
keys | object | Unique keys associated with the measure set. e.g. channelId, agentId. | |
Note: All values are returned in string form (even numbers). | Any | ||
eventAction | string | Event Action. Can be either UPSERT (update or insert) to DELETE. | UPSERT, DELETE |
measureProducerId | string | The unique ID for the measure dimensions produced from Analytics. Measures are defined on entities such as contacts, agents etc, and are typically counts or durations, for example the number of contacts waiting, the number of contacts offered to agents. | Any |
payloadType | string | The payloadType Enum indicates if Analytics is sending “initialization” or “live” messages: |
- INITIALIZING: The payload contains a snapshot of the most up to date values for all the measures calculated for the Measure Producer.
- LIVE: The payload contains newly calculated measures. | INITIALIZING, LIVE |
| measures | object | Property which can be calculated by events in the system. e.g. AgentState, Time On Hold, Calls Waiting, Total Call Duration.
Note: All values are returned in string form (even numbers). | Any |
| eventSourceId | string | The unique ID for the source of incoming events for Analytics. | Any |
| accountId | string | The unique ID of the customer account | Any |
Examples of payload
example 1
Example of an "INITIALIZING" message.
{
"accountId": "EZCLTR",
"keys": {
"channelId": "EMAIL"
},
"eventAction": "UPSERT",
"eventSourceId": "IXCC_1.0.0",
"measureProducerId": "Queue_itd_1.0.0",
"payloadType": "INITIALIZING",
"measures": {
"coached": "2",
"isDefaultQueue": "false",
"activeDuration": "922",
"active": "0",
"activeEngagementsInACW": "0",
"contactsQueueing": "2",
"Answered": "4",
"coachingDuration": "309",
"queueName": "Natella",
"coachedDuration": "309",
"activeAgentsInACW": "0",
"alertDuration": "5",
"Completed": "4",
"coaching": "2",
"Offered": "4"
}
}
example 2
Example of an "LIVE" message.
{
"accountId": "EZCLTR",
"keys": {
"agentId": "9f44ed4e-24ee-4e50-98af-02582e440be5"
},
"eventAction": "UPSERT",
"eventSourceId": "IXCC_1.0.0",
"measureProducerId": "Agent_itd_1.0.0",
"payloadType": "LIVE",
"measures": {
"reasonCodeName": "N/A",
"timeInState": "1643645393849",
"agentLoginId": "[email protected]",
"userStatus": "Live",
"agentLastName": "agent7",
"agentDisplayName": "agent7",
"timeOnHold": "0",
"timeLoggedIn": "1643645393849",
"timeActive": "0",
"idleTimeDuration": "36000",
"agentLogonDuration": "36000",
"timeInACW": "0",
"agentState": "READY",
"agentFirstName": "agent7"
}
}
Tags
- Event Data
Message pong
pong
Server pong response to a ping message. The ping message is sent by the client to the server using the programming lanuguage websocket framework library API ping method. The client listens for the pong message with the specialized pong listener of the programming language websocket framework library API.
Tags
- Heartbeat
Message authenticationResponse
authenticationResponse
Authentication response message sent to the client after websocket authentication.
Payload
Name | Type | Description | Accepted values |
---|---|---|---|
event (required) | string | authenticationResponse - A constant parameter. | Any |
status | string | The notificationType Enum indicates the type of the notification, that can be: |
- CONNECTION_CONFIRMED: Connection was confirmed
- CONNECTION_FAILED_INVALID_TOKEN: Authentication token is invalid
- CONNECTION_FAILED_UNKNOWN_SUBSCRIPTION: Unknown Subscription, can be for a subscription that never existed or one that is no longer active
- CONNECTION_FAILED_INTERNAL_SERVER_ERROR: Server Error, client can retry later
- CONNECTION_FAILED_CONSTRAINT_VIOLATION: Client issue, malformed client request, client must update payload and rerty | CONNECTION_CONFIRMED, CONNECTION_FAILED_INVALID_TOKEN, CONNECTION_FAILED_UNKNOWN_SUBSCRIPTION, CONNECTION_FAILED_INTERNAL_SERVER_ERROR, CONNECTION_FAILED_CONSTRAINT_VIOLATION |
Examples of payload
authenticationMessage
Example of a authentication message to client.
{
"event": "authenticationResponse",
"status": "CONNECTION_CONFIRMED"
}
Tags
- Authentication
Updated 2 months ago