A live wallboard for Genesys Cloud CX. It loads the full agent roster with group and
queue structure over REST, then streams every presence and routing-status change over the Genesys
Notifications WebSocket — a 270° instrument gauge, a nine-tile KPI strip, per-group and per-queue
agent cards and a live transition ticker, all updating the moment an agent changes state. No
polling, no refresh.
Continuously integrated and updated. This is a published sample of the user guide. The App Suite changes frequently, so this page may not reflect the latest features, screens and behaviour. The current guide is available in the application through the QVCCS apps portal, included with every Managed Professional Services tier.
At a glance
agent-presence wallboard
live WebSocket stream
multi-user
dark wallboard UI
zero persistence
read-only against Genesys
Security at a glance
CX Pulse
Read-only (manages only its own notification channel)
Sign-in
OAuth client credentials you supply; held on the server for your session only and never sent to the browser
Stores
Nothing at rest; presence is displayed, then superseded, and the wallboard state lives in your browser tab
AI
No AI features are described in the user guide
Exports
None by design (live wallboard)
Genesys Cloud permissions
A role with view access to users, groups, routing queues (routing:queue:view) and presence definitions; no write permissions
CX Pulse is a real-time contact-centre wallboard. It shows the current presence and
routing status of every agent in your Genesys Cloud organisation, organised by Genesys group or
routing queue, and
keeps that picture live: the moment an agent goes Available, joins the queue, steps away or misses
an offered interaction, the dashboard updates — pushed over a WebSocket, not polled.
Supervisor line-of-sight — who is on queue right now, who is available, who has been
on break for 40 minutes. One dot per agent, clustered by state, per group or queue.
Floor summary at a glance — the KPI strip totals Online, Available, On Queue,
Ineligible, Away/Break, Meal, Meeting, Training and Overdue; hovering any tile lists exactly
which agents it is counting.
“Forgot to log off” detection — the Overdue tile counts agents held in a
non-productive state for more than 61 minutes.
Missed-offer visibility — Ineligible (Genesys routing status
NOT_RESPONDING) is split out of On Queue, so “system removed them from routing”
never masquerades as “taking calls”.
Presence hygiene — the live ticker records every state transition as it happens, with
a click-to-locate jump to the agent’s dot and an exact wall-clock timestamp on hover.
Read-only. CX Pulse never changes an agent’s state and writes nothing to
your org. The only POST/PUT/DELETE calls it makes manage its own notification channel —
plumbing for the read stream.
2Quick start
Open the app — without a session you are redirected to the sign-in page.
Sign in — pick the Region (14 Genesys regions), then
paste the Client ID and Client Secret of an OAuth client-credentials
grant (see §6 for what it must be allowed to read). The app validates the credentials with Genesys and opens the dashboard.
Watch the radar splash — boot loads org profile → presence definitions → agent
roster → groups & membership → queue list, with a progress bar narrating each step.
Show a team — all groups and queues start hidden (zero subscriptions). Click a
group or queue row in the sidebar to show it: its card appears, live subscriptions are pushed
for its members, and the badge goes LIVE. (A queue’s first show fetches its member
list — the row reads loading… for a moment; it’s cached for the session.)
Read the floor — gauge for the overall shape, KPI tiles for totals (hover for the
agent lists), group cards for individuals, ticker for the play-by-play.
No demo mode. Unlike some QVCCS apps, CX Pulse has no synthetic org —
real Genesys credentials are required. This guide, however, is readable without signing in.
3UI walkthrough
Top bar & search
Brand + organisation name — the org name comes from
GET /organizations/me at boot.
Search agent… — dims every agent dot whose name doesn’t contain the typed text
(case-insensitive). Layout is preserved, so you keep spatial memory of the floor.
Agent total — the full roster count (all agents, visible or not).
LIVE / CONNECTING / RECONNECTING badge — the WebSocket state.
📖 Guide — this manual, in a new tab. Disconnect — closes the live stream, ends your session (and discards your credentials with it), returns to sign-in.
Sidebar — live overview gauge, groups & queues
Precision gauge — a 270° instrument arc with tick marks every 5% and labels at
0/25/50/75/100. The full arc represents all agents in visible groups and queues; filled segments
stack Available (green), On Queue (blue), Away (amber) and Busy (red); the unfilled remainder
is the offline share. The centre reads Online / total; a five-row legend gives exact
counts (Available · On queue · Away/break · Busy/DND · Offline).
Groups list — one row per Genesys group plus Ungrouped (agents in no loaded
group), each showing online/total and a show / hide control. Visibility
drives the WebSocket subscription list (§5). Hidden rows are dimmed; hovering shows the full
group name.
Queues list — one row per routing queue, same show/hide semantics. Before a queue is
first shown its row displays the org’s member count as a size hint; the first show
fetches its membership (cached for the session), builds its card and subscribes its members.
An agent can appear in a group card and a queue card at once — both stay in sync, and their
subscription is counted once.
Filter groups… / Filter queues… — each list live-filters by name substring; a “No
groups/queues match” hint appears when nothing does. The filters survive re-renders.
KPI metrics strip
Nine tiles across the top of the content pane. Buckets are mutually exclusive — each
non-offline agent is classified once, from the derived display state (§4), so an On-Queue
agent whose underlying presence is Meal counts once, as On Queue.
KPI metrics strip
Tile
Counts
Sub-label
Online
Every visible agent not Offline (the gross logged-in count — the one
tile that overlaps the others)
agents logged in
Available
Display state Available
the longest-available agent’s
first name and how long they’ve waited
On Queue
Routing status IDLE / INTERACTING / COMMUNICATING
idle /
interacting
Ineligible
Routing status NOT_RESPONDING (missed offer / system-removed)
missed offer / system
Away / Break
Primary Away or Break — includes every org-defined secondary that
resolves under the Away primary (“Comfort Break”, “Personal”, …)
stepped away
Meal
Primary Meal
lunch break
Meeting
Primary Meeting or In Conference
in a meeting
Training
Primary Training
training session
Overdue ⚠
Any non-productive state (everything except Available, On Queue,
Offline) held for > 61 min — the “forgot to log off” check. Orthogonal to the other
tiles: an agent counts in their state tile and here.
“N agents >61 min
unavailable” / “no issues detected”
Agents whose display state is Busy, Idle or Out of Office have no tile of their own —
they count in Online (and Overdue when held long enough) only. Hovering a tile opens an
alphabetical list of the matching agents with their time-in-state; the list stays open while your
cursor is on it.
Group & queue cards
Header — group or queue name (queue cards carry a blue QUEUE chip; otherwise
the two kinds behave identically), a stacked proportional status bar (available / on queue /
away / busy / offline), online/total, and a radar “streaming” indicator.
Agent grid — one dot per agent (colour + glyph = state, small label = time in
state), clustered by status in a fixed order (Available → On Queue → Busy → Away family →
Offline). On a member’s state change the dot recolours and flashes, the card fires a
radar ping plus a brief background flash, the group name and its sidebar row flash, and
the agent re-clusters into its new status block (in-flight animations survive the move).
Stats panel — utilisation (“N% online”), per-state counts, and — when any member has
been in an Away/Busy-family state for more than 15 minutes — an amber Overdue
row counting them.
Stale highlight — those same >15-minute agents get a highlighted ring on their
dot, refreshed every 30 s.
Two “overdue” thresholds. The group-card Overdue row and the dot
highlight use the 15-minute stale rule (Away/Busy families — “glance at this agent now”).
The KPI Overdue tile uses the separate 61-minute rule over all non-productive
states (“probably forgot to log off”). Same word, deliberately different jobs.
Live ticker
A newsroom-style strip along the bottom. Every meaningful display-state transition appends a
chip: state icon + agent name + → + new state.
Recent changes only — at most 14 chips; each retires 30 s after it
appears (older ones slide out left when the row overflows). Per-agent 1 s dedup
swallows duplicate WebSocket frames; an agent’s very first sighting seeds silently so boot
doesn’t flood the strip.
Hover pauses the strip’s animations (a “paused” hint fades in) and pops a
digital-watch readout of the exact wall-clock time the change was received
(HH:MM:SS, plus “Ns ago”).
Click a chip to locate the agent: the grid smooth-scrolls to their dot and fires a
locate pulse. If the agent is only in hidden groups/queues, the relevant sidebar rows flash
instead — the hint that you need to un-hide that group or queue.
Status bar & tooltips
Status bar (bottom) — connection state and message (Live streaming,
Live — no groups or queues selected, Reconnecting…, subscription/boot warnings), the
UPDATED time of the last processed event, and the subscription counter, e.g.
412 / 1000 subscriptions (41%).
Agent tooltip — hover any dot for the agent’s name, their exact org-defined state
label (“Comfort Break”, not just “Away”) and time in state. On Queue always shows “On Queue”
(more meaningful than the underlying secondary).
4The presence model
Each agent is tracked as three independent fields, because Genesys reports them independently:
systemPresence — the primary category (Available, Away, Busy, Meal, …).
presenceLabel — the org-defined secondary’s display name (“Break”, “Lunch”,
“Comfort Break”), resolved through the presence-definitions cache.
routingStatus — the queue-side status, tracked separately so going on/off queue
never loses the underlying presence.
How a dot gets its colour
The displayed state is derived on every change:
How a dot gets its colour
Routing status
Display state
NOT_RESPONDING
Ineligible — missed an offered interaction,
or the system removed the agent from routing
IDLE / INTERACTING / COMMUNICATING
On Queue — logged on and waiting, handling or wrapping
OFF_QUEUE or none
The system presence (Available, Away,
Meal, Meeting, Training, Busy, …)
The OFF_QUEUE fallback matters: when an agent leaves the queue the dashboard reverts them to
their underlying presence instead of leaving them visually stuck On Queue. Conversely, a presence
change while on queue updates the tooltip label without knocking the agent out of On Queue.
Presence definitions & string normalisation
At boot the org’s full presence-definition set is cached (defId → label + primary,
preferring the en_US language label). Live events reference definitions by id, so the
cache is what lets a custom secondary keep its own label and land under the right primary
category. Genesys also emits the primary enum in three different spellings depending on
surface — REST "On Queue", WebSocket "ON_QUEUE", definitions
"AVAILABLE"-style — and a normaliser folds all three into one key set. (Historically,
missing this was why agents “flipped to Offline” the moment they changed state live.)
States, families & thresholds
States, families & thresholds
Display state
Gauge family
Colour
Available
available
green #22c55e
On Queue
on queue
blue #3b82f6 (dot “breathes”)
Ineligible
own bucket (KPI only)
red #ef4444
Busy
busy
red #ef4444
Away · Idle · Meal · Break · Out of Office
away
amber #f59e0b
Meeting · In Conference
away
soft blue #60a5fa
Training
away
sky #0ea5e9
Offline
offline
slate #94a3b8 (dot dimmed)
Stale alert — Away/Busy-family state held > 15 min → dot highlight +
group-card Overdue row.
KPI Overdue — any non-productive state (incl. Ineligible) held > 61 min.
Time in state — from the presence record’s modifiedDate at boot, or the
event’s arrival time mid-session; duration labels and stale flags re-sweep every 30 s.
5Live streaming & subscriptions
Boot sequence (what the radar splash is doing)
GET /organizations/me — org name for the top bar (and proof the session works).
GET /presencedefinitions — the definitions cache (paged).
GET /users?expand=presence,routingStatus — the full roster with current state,
paged 100 at a time.
GET /groups, then GET /groups/{id}/members for each — membership
resolved in parallel batches of 8. A group whose member fetch fails is logged, counted,
and surfaced in the status bar (“N group(s) failed to load — see console”); it is dropped for
this boot and its agents fall into Ungrouped. Groups with zero members are dropped
too.
GET /routing/queues — the queue list (paged). Membership is not fetched
here: each queue’s GET /routing/queues/{id}/members runs lazily the first time
that queue is shown, then is cached for the session — boot cost stays one listing even with
hundreds of queues. A 403 here (client can’t read queues) is non-fatal: the Queues rail
just stays empty.
Render. All groups and queues start hidden → zero subscriptions.
POST /notifications/channels — create a notification channel, then open its
wss://…connectUri directly to Genesys.
The subscription budget
Watching an agent costs 2 topics — v2.users.{id}.presence and
v2.users.{id}.routingStatus. Genesys hard-caps a channel at 1000 topics,
so at most 500 agents stream concurrently.
Every show/hide toggle triggers a PUT that replaces the entire topic list — the
channel can never creep past the cap. Above it, the list truncates and the status bar warns
“capped at 500. Hide some groups or queues.” Agents beyond the cap keep their boot-time state
but do not stream.
Hiding every group and queue issues a DELETE that clears all subscriptions (“Live —
no groups or queues selected”). The subscription set is a union: an agent visible via
both a group and a queue still costs only their 2 topics.
Race-plug snapshot — after each successful PUT, the app re-fetches presence for the
just-subscribed users over REST (/users?id=…, chunks of 50), so any change that
happened between roster load and subscription activation isn’t silently lost.
Channel lifecycle
Heartbeat — Genesys sends channel.metadata every ~30 s; the client
replies {"message":"ping"} so NAT boxes and corporate firewalls don’t kill the
“idle” socket.
Expiry — channels live ~24 h. ~30 s before expiry Genesys sends
v2.system.socket_closing; the client immediately creates a fresh channel and
re-subscribes — no visible gap.
Unexpected close — the client waits 5 s and creates a new channel (stale
connectUris 404 forever, so reconnecting to the old one is deliberately
avoided).
Politeness to the API
All list calls page 100 at a time; group membership resolves 8 groups in parallel.
On a Genesys 429 the client waits Retry-After (default 5 s) plus up to
30% jitter, capped at 60 s, and retries up to 3 times.
After boot, updates are pure push — a quiet floor costs nothing.
6Genesys endpoints & permissions
Every REST call below is made on your behalf by the app, which holds the credentials; the live event stream is the one direct browser→Genesys connection.
boot (list) · first show of a queue
(members, cached)
Queue rail; queue cards’ membership
POST
/api/v2/notifications/channels
boot · reconnect · renewal
Create a notification channel →
{id, connectUri}
PUT
/api/v2/notifications/channels/{id}/subscriptions
every show/hide
Replace the full topic list (never exceeds 1000)
DELETE
/api/v2/notifications/channels/{id}/subscriptions
everything hidden
Clear every subscription
GET
wss://…<connectUri>
continuous
The event stream itself (browser → Genesys direct)
Permissions
A client-credentials OAuth client is authorised by the roles assigned to it —
OAuth scope strings apply to user-context grants, not this one. Every call above is a read of
directory/presence data or self-service notification plumbing: give the client a role with
view access to users, groups, routing queues and presence definitions (for queues that is
routing:queue:view — without it the Queues rail is empty and everything else still
works), and it has everything it needs.
Notification-channel management requires no extra permission — any authenticated client may create
a channel and subscribe to presence/routing topics. No write or admin permission is ever used.
403 on one endpoint? The client’s role lacks the matching view
permission. Fix the role, then sign out and back in — token capabilities are minted at
sign-in.
7Storage, privacy & security
Zero persistence. No database and nothing written to storage. Sessions exist only while you are signed in; the wallboard state lives in the browser tab. Sign in again and the whole picture rebuilds from Genesys.
Credentials stay on the server. Your client id/secret, region and OAuth token are held on the server for your session only and are never sent to the browser, which holds only a secure session cookie. Signing out — or a period of inactivity — ends the session and discards them.
Session hygiene — sessions end after a period of inactivity; re-signing in with the same Client ID + region reclaims your own earlier session.
Login convenience — the sign-in page remembers your Client ID and region (never the secret) in your browser.
Presence data is never stored — it is displayed, then superseded by the next event. Hidden groups aren’t even subscribed: you only stream the teams you are actually watching — the quota lever doubles as a privacy courtesy.
Network posture — the browser needs direct WebSocket access to wss://streaming.<genesys-domain> for the stream, and fetches its webfonts from Google Fonts (cosmetic — system fonts take over if blocked). All REST traffic goes through the app.
8Technology
Web application — signs in to Genesys, holds your session and makes every Genesys REST call on your behalf, transparently refreshing the token when it expires. The dashboard can’t be opened without a signed-in session.
Browser interface — a single dark wallboard page with the SVG gauge, radar splash, cards and ticker.
Streaming — the browser opens the notification channel’s connectUri WebSocket directly to Genesys; only REST goes through the app (§5 covers the channel lifecycle and topics).
9Troubleshooting
“The service is busy – try again shortly”
The service is handling as many sign-ins as it can. Re-signing in with the same Client ID + region reclaims your own earlier session; otherwise try again shortly or ask a colleague to Disconnect.
Badge stuck on RECONNECTING
The client creates a
fresh channel every 5 s after a close; if it never recovers, (a) the Genesys token/session may be
invalid — sign out and in; (b) a firewall may block wss://streaming.<domain> — the browser needs direct WebSocket access to Genesys; only REST goes through the app.
Agents flip to Offline when they change state / secondary labels missing
The presence-definitions fetch failed at boot (console: “presence definitions fetch
failed”). Without the cache, org-defined secondaries can’t be resolved. Reload; check the OAuth
client can read /api/v2/presencedefinitions.
A group is missing from the sidebar / agents appear under “Ungrouped” wrongly
That group’s member fetch failed during boot — the status bar shows “N group(s) failed to
load — see console” and the group is dropped for this boot, its agents falling into Ungrouped.
(Groups with zero members are dropped silently by design.) Persistent failures usually mean the
OAuth client lacks group read visibility, or a very large dynamic group is timing out —
reload to retry.
“capped at 500. Hide some groups or queues.”
Genesys enforces 1000 topics per channel and each agent costs 2. The topic list truncates at
the cap: agents beyond it keep their boot-time state but don’t stream. Hide groups or queues you
don’t need — the PUT replaces the whole list, so the counter drops immediately.
Fine all day, then “Notification channel expiring — opening a new one…”
Normal. Channels live ~24 h; Genesys warns ~30 s ahead with
v2.system.socket_closing and CX Pulse pre-emptively renews. If it escalates to
“Channel renewal failed”, sign out and in.
Everything suddenly redirects to the login page
Your session has ended — after a period of inactivity, or because the service was restarted — so the dashboard returns to the sign-in page. Sign in again.
Boot is slow on a big org
Boot pages users 100 at a time and resolves group membership 8 groups in parallel; 429s
retry after Retry-After + jitter, up to 3 attempts. Thousands of users and hundreds
of groups can take a minute. Once booted, updates are push-based and cost nothing.
Does hiding a group or queue stop data collection?
Yes — hidden groups and queues contribute no topics to the channel (the PUT replaces the
whole list; a member also visible elsewhere keeps streaming via that card). It is both the
quota lever and a privacy courtesy.
Why can two tabs disagree for a moment?
Each tab owns its own channel and subscription set. A tab that just subscribed may lag until
its race-plug snapshot lands; both converge on the next event.
Where did an agent’s ticker chip go?
Chips retire 30 s after they appear (max 14 on screen) — the ticker shows recent
transitions, not history. Hover to pause it while you read; click a chip to jump to the
agent.
No CSV/PDF export?
Deliberate — this is a live wallboard and the data is a moving target. For point-in-time
configuration exports use the Config Validator app.
QVCCS CX Pulse — real-time agent presence & routing wallboard for Genesys Cloud CX. Read-only against the Genesys APIs; zero persistence.
Continuously integrated and updated. This is a published sample of the user guide. The App Suite changes frequently, so this page may not reflect the latest features, screens and behaviour. The current guide is available in the application through the QVCCS apps portal, included with every Managed Professional Services tier.
Included at every tier
Use CX Pulse with QVCCS Managed Professional Services.
The App Suite comes with every Bronze, Silver, Gold and Diamond subscription, used by our engineers and your administrators alike – backed by the certified QVCCS bench.