Designing Real-Time Interaction Dashboards using the Analytics Notification Service (WebSockets)

How-To-Articles
1

Designing Real-Time Interaction Dashboards using the Analytics Notification Service (WebSockets)

What This Guide Covers

  • Bypassing the limitations of the standard REST Analytics API (which relies on polling and aggregation delays) to build true real-time “wallboard” dashboards.
  • Subscribing to the Genesys Cloud Notification API (WebSockets) using the v2.analytics.queues.{id}.observations topic.
  • Architecting a Node.js/React frontend that ingests the WebSocket stream to instantly display live Queue Wait Times, Active Agents, and Abandon Rates with sub-second latency.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 1, 2, or 3.
  • Permissions: Analytics > Queue Observation > View, Notifications > Subscription > Add.
  • Infrastructure: A backend server (Node.js/Python) to maintain the persistent WebSocket connection, and a frontend framework (React/Vue) for visualization.

The Implementation Deep-Dive

1. The Polling Problem in Real-Time Dashboards

The most common mistake developers make when building a custom “Wallboard” (a screen displayed on the contact center floor showing live metrics) is using the POST /api/v2/analytics/queues/observations/query REST API in a setInterval loop.

The Trap:
Polling the REST API every 5 seconds is a catastrophic anti-pattern. First, you will rapidly hit the 300 requests/minute API rate limit, crashing your application. Second, the REST Analytics API is designed for aggregate reporting and inherently has a 1-to-3 minute replication delay. If your Wallboard shows 0 calls in queue, but a supervisor hears 5 phones ringing, the Wallboard loses all credibility.

2. The Solution: WebSockets and the Notification API

To achieve sub-second, push-based updates, you must use the Genesys Cloud Notification API.

Implementation Steps (Node.js Backend):

  1. Authenticate: Use Client Credentials to obtain an OAuth token.
  2. Create a Channel: Call POST /api/v2/notifications/channels. Genesys Cloud will return a connectUri (the WebSocket URL) and an id (the Channel ID).
  3. Open the Socket: Use a WebSocket library (like ws in Node.js) to connect to the connectUri.
const WebSocket = require('ws');
const ws = new WebSocket(channel.connectUri);

ws.on('message', (data) => {
    const event = JSON.parse(data);
    if (event.topicName !== 'channel.metadata') {
        processQueueUpdate(event);
    }
});

3. Subscribing to Analytics Topics

Connecting to the WebSocket is not enough; you must tell Genesys Cloud what data to stream down that pipe.

Implementation Steps:

  1. Define the Topics: We want real-time queue observations. The topic format is v2.analytics.queues.{queueId}.observations.
  2. Subscribe: Send a POST request to /api/v2/notifications/channels/{channel.id}/subscriptions with an array of the topics you want to monitor.
[
  {"id": "v2.analytics.queues.3b...a1.observations"},
  {"id": "v2.analytics.queues.8c...f2.observations"}
]
  1. The Payload: Genesys Cloud will now instantly push a JSON payload down the WebSocket every time a queue metric changes (e.g., an agent goes On Queue, a call enters the queue, a call abandons).

4. Parsing the WebSocket Payload for Wallboards

The data returned by the observations topic is extremely dense. It is not pre-calculated.

Architectural Reasoning:
The payload does not give you a neat variable like Total_Wait_Time = 45s. It gives you arrays of metrics (like oWaiting, oInteracting, oOnQueueUsers). Your backend must parse these and calculate the specific KPIs your Wallboard needs.

Implementation Steps (Parsing Logic):

  1. When the WebSocket fires, extract the data.data object.
  2. Iterate through the metrics array.
  3. Active Calls in Queue: Look for metric: "oWaiting". The stats.count value represents the real-time number of calls waiting.
  4. Longest Wait Time: Look for metric: "oWaiting". The stats.max value (in milliseconds) represents the call that has been holding the longest.
  5. Agents on Queue: Look for metric: "oOnQueueUsers". The stats.count represents agents currently eligible to take calls.
  6. Push this parsed, clean data from your Node.js backend to your React frontend using a secondary WebSocket (e.g., Socket.io), ensuring your frontend updates instantly without hitting Genesys Cloud APIs.

Validation, Edge Cases & Troubleshooting

Edge Case 1: WebSocket Heartbeats and Disconnects

  • The Failure Condition: Your Wallboard runs perfectly on Monday. On Tuesday morning, the screen freezes. It shows 5 calls in queue forever, even though the actual queue is empty.
  • The Root Cause: WebSockets are persistent TCP connections. Firewalls, network blips, or Genesys Cloud server restarts will occasionally sever the connection. If your code does not detect the disconnect, it will freeze. Furthermore, Genesys Cloud requires you to respond to “Heartbeat” pings.
  • The Solution:
    1. Implement a Ping/Pong heartbeat check. If the server does not receive a channel.metadata heartbeat event within 30 seconds, force a reconnection.
    2. Implement aggressive retry logic (Exponential Backoff). If the socket drops, your script must automatically request a new connectUri, re-subscribe to all topics, and fetch a baseline snapshot via the REST API to fill in any data missed during the downtime.

Edge Case 2: Maximum Subscription Limits

  • The Failure Condition: You try to subscribe to 1,500 queues across your global enterprise. The API rejects the request with a 400 Bad Request.
  • The Root Cause: A single Notification Channel supports a maximum of 1,000 topic subscriptions.
  • The Solution: If you need to monitor more than 1,000 queues, you must shard your architecture. Create a “Channel Manager” script that spawns multiple WebSockets (Channel 1 handles queues 1-1000, Channel 2 handles queues 1001-2000). Note: OAuth clients also have a maximum limit of 20 concurrent channels per token.

Official References