Building a Custom Wallboard Using Server-Sent Events and the Stats API

How-To-Articles
1

Building a Custom Wallboard Using Server-Sent Events and the Stats API

Executive Summary & Architectural Context

Walk into any high-volume contact center, and you will see the same scene: ten giant flat-screen TVs mounted to the walls, each displaying a “Standard” platform wallboard. The font is too small to read from 20 feet away, half the screen is wasted on metrics the team doesn’t care about (like “Email Backlog” for a voice-only team), and the color scheme is a dreary gray that provides zero urgency. Worse, once a week, the browser on the dedicated wallboard PC freezes, and a supervisor has to find a ladder, a wireless mouse, and a keyboard to manually refresh the page.

A Principal Architect doesn’t use the default wallboard; they build a Custom Streaming Wallboard. This is a dedicated web application designed specifically for high-visibility TV displays. It uses Server-Sent Events (SSE) or WebSockets to push real-time queue statistics from the Analytics Stats API directly to the screen. It features “High-Contrast Alerting” that changes the entire background of the screen based on performance thresholds, ensuring that every agent on the floor knows the instant the service level is in danger.

This masterclass details how to architect a real-time wallboard engine that is resilient, highly visible, and zero-maintenance for the operational team.

Prerequisites, Roles & Licensing

Licensing & Permissions

  • Licensing Tier: Genesys Cloud CX 1, 2, or 3.
  • Granular Permissions:
    • Analytics > Subscription > View, Add
    • Analytics > Observation > View
  • OAuth Scopes: analytics, notifications.
  • External Dependencies:
    • TV Hardware: Smart TVs with a modern browser or a compute stick (Chromecast, NUC).
    • Middleware: A lightweight Node.js or Go server to aggregate and push the events.

The Implementation Deep-Dive

1. The Real-Time Strategy: SSE vs. WebSockets

While WebSockets are bi-directional, a wallboard is a “One-Way” data consumer. Server-Sent Events (SSE) are often superior for wallboards because they are lighter on the client (browser) and include automatic reconnection logic by default.

The Data Flow:

  1. The Middleware: Subscribes to the Genesys Cloud Notification API for queue observations.
  2. The Aggregator: Normalizes the “Event Storm” into a clean JSON packet every 1 second.
  3. The Emitter: Broadcasts this packet to all connected TVs via an SSE stream.

2. Implementing the SSE Emitter (Node.js)

const express = require('express');
const app = express();

// 1. Setup SSE Endpoint
app.get('/wallboard-stream', (req, res) => {
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    // 2. Function to push data to the TV
    const sendUpdate = (data) => {
        res.write(`data: ${JSON.stringify(data)}\n\n`);
    };

    // 3. Listen for events from our Genesys Subscription logic
    eventEmitter.on('stats_update', (newStats) => {
        sendUpdate(newStats);
    });
});

3. The Frontend: “Designed for Distance”

The CSS for a wallboard is different than a standard website. You must use Relative Units (vh/vw) and High-Contrast Colors.

The “Alert Mode” Pattern:
If the Service Level (SL) drops below 80%, the entire background should flash.

/* wallboard.css */
.critical-alert {
    background-color: #FF0000 !important; /* Pure Red */
    animation: blinker 1s linear infinite;
}

@keyframes blinker {
    50% { opacity: 0.5; }
}

4. “The Trap”: The “Stale Socket” Ghost

The Scenario: Your wallboard has been running perfectly for 3 days. Suddenly, the “Calls Waiting” number gets stuck at 4. The floor is quiet, but the TV says there’s a crisis.

The Catastrophe: The WebSocket between your middleware and Genesys Cloud dropped, or the SSE stream between your middleware and the TV hung. Because there is no visual “Pulse” on the screen, the supervisors don’t realize they are looking at data from two hours ago. They start cancelling agent breaks based on a “Crisis” that doesn’t exist.

The Principal Architect’s Solution: The “Digital Pulse” & Auto-Refresh

  1. The Heartbeat: Every 10 seconds, send a timestamp in the SSE stream.
  2. The Visual Pulse: Display a small “Green Dot” in the corner of the TV that blinks every time a packet is received.
  3. The Watchdog Script (Frontend):
    let lastUpdate = Date.now();
setInterval(() => {
    if (Date.now() - lastUpdate > 30000) {
        // If no data for 30 seconds, the stream is dead.
        window.location.reload(); // Force a hard refresh
    }
}, 5000);

Advanced: Performance Threshold Logic

A wallboard shouldn’t just show numbers; it should show Context.

Implementation Detail:
Use a Dynamic Scalar.

  • If CallsWaiting == 0, display “READY” in Green.
  • If CallsWaiting > 0 and SLA > 90, display the number in White.
  • If CallsWaiting > 5 or SLA < 80, display “WARNING” in Yellow.
  • If SLA < 70, enter “CRITICAL” mode.

This “Tiered Urgency” allows a supervisor to gauge the room’s health in a 0.5-second glance from across the floor.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Low-Memory TV Browsers

The failure condition: After 12 hours of running, the built-in browser on the Smart TV crashes with an “Out of Memory” error.
The root cause: Memory leaks in complex JavaScript frameworks (React/Vue) or unoptimized DOM updates.
The solution: Use Vanilla JavaScript. Do not use a framework for a wallboard. Update the innerText of specific <span> elements instead of re-rendering the whole page. This ensures the wallboard can run for months without a reboot.

Edge Case 2: Network Latency “Jitter”

The failure condition: The “Calls Waiting” number bounces rapidly between 2 and 8 every second, creating a nervous, “jittery” visual experience for the agents.
The root cause: High-frequency raw events without smoothing.
The solution: Implement Time-Window Averaging in your middleware. Send the moving average of the last 5 seconds of data to the wallboard to provide a stable, readable trend line.

Reporting & ROI Analysis

The success of a custom wallboard is measured by Operational Agility.

Metrics to Monitor:

  • Supervisor Reaction Time: How long from an SL drop to an agent move? (Compare “Standard” vs “Custom”).
  • Wallboard Uptime: Percentage of time the TV is showing current, non-stale data.
  • Agent Sentiment: Floor-level feedback on readability and “Visual Stress.”

Target ROI: By improving visual urgency, you can typically reduce “Response Latency” to queue spikes by 25-40%, resulting in a more stable Service Level and fewer “Red Zone” incidents.

Official References