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
• Channels

Servers

production Server

URL Variables

Security Requirements

Channels

/v1/analytics/realtime Channel

publish Operation

Ping Server.

Accepts one of the following messages:

Message 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

The first message the client should send to server after establish the connection must be an authentication message.

Payload

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

Outgoing Realtime Data

Accepts one of the following messages:

Message Event data

Payload

• 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

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

Authentication response message sent to the client after websocket authentication.

Payload

• 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