Live Call Map

1What it is

QVCCS Live Call Map is a real-time operations dashboard for Genesys Cloud CX. It subscribes to your org’s notification streams and paints a live picture of the contact centre:

• World map — a clustered marker for every active conversation, geolocated from the caller’s number (ANI) or, for outbound, the dialled number (DNIS). Voice, chat, email, messaging, callback, bot, workflow, co-browse, video and social interactions are all tracked.
• Live agent presence — on-queue / online / wrap-up counts, driven by per-agent presence and routing-status events and re-seeded by a 10-second authoritative poll.
• Queue health — per-queue agents total/idle, waiting conversations, assigned-but-unanswered surfacing, wrap-up code tallies.
• Analytics tooling — a 24-hour traffic chart, historical replay of any time window, a geographic heatmap of up to 30 days of conversations, MOS/latency quality alerts, and a raw JSON capture terminal for support engineers.

Its defining design decision is isolation per org: every signed-in set of credentials gets its own separate workspace (§4), with its own Genesys connection and its own data. Credentials are held on the server, never written to storage and never sent to the browser.

2Quick start

1. Open the app — visitors who are not signed in always land on the sign-in page.
2. Sign in — pick your Region, enter the Client ID and Client Secret of a Genesys OAuth client-credentials client with the read-only permissions from §6, and press Sign in. The app checks the credentials with Genesys first, then opens (or re-attaches you to) your org's workspace.
3. Watch it connect — the connect progress steps stream live (auth → queues → channel → preload); markers appear as the preload completes and the push stream takes over.
4. Explore — click any marker for the full call story; open Queue Health (Q), the 24-hour chart (C), Replay (X) or the Heatmap from the toolbar.
5. Sign out — the ⎋ Logout button shows the real teardown as it happens: the app releases its Genesys notification channels and ends your session. Closing the tab without logging out is also safe — the workspace is closed automatically shortly after your browser disconnects.

Your Client ID + region are remembered in your browser for next time; the secret never is.

3The map

Basemap & layers

The base cartography is Esri World Gray Canvas — a keyless, no-registration raster basemap designed for data overlays, in matching Light and Dark flavours plus a separate Reference labels layer drawn beneath the markers. Esri’s canvas tiles need no key at all.

• Zoom — the basemap's native detail stops at zoom 16; zooms 17–19 enlarge those tiles rather than erroring.
• Automatic OSM fallback — after 8 tile-load errors the map swaps itself to the standard OpenStreetMap layer (keyless by charter), logs a warning to the event log, and the fallback sticks across theme changes for the rest of the session — insurance against the basemap provider changing its terms.
• Theme — dark by default; the ☀️ button cycles light / dark / follow system (persisted). Switching theme swaps the Esri Light/Dark base + labels pair 1:1.
• Day/night terminator — the 🌓 button overlays a translucent night-side polygon (approximate solar position, accurate to ~±2°, re-rendered every 60 s; toggle persisted).

Live call markers

• Markers are clustered and coloured by media type and state; long-waiting calls pulse faster and shift “warm/hot”.
• Marker popup — caller/ANI, dialled number, queue, agent (with presence), flow journey (first → current flow, queue entry), state timeline, hold/mute/recording flags, transfers, wrap-up code once submitted, geo method + confidence, and any quality data.
• Media filter chips — voice · email · chat · messaging · bot · workflow · co-browse · video · social · callback. Filtering is client-side; markers hide instantly.
• “⊘ Unknown” column — conversations whose origin could not be geo-resolved are listed beside the map instead of being faked onto it. All emails land here by design (see below).

Geolocation pipeline

Phone-number based, first match wins:

1. US/CA NPA table — area code → curated city centroid (updated through early 2026).
2. libphonenumber — if the number is GEOGRAPHIC (fixed line), a city-level lookup against a bundled gazetteer (~150 countries).
3. Curated sub-country prefixes — fills gaps at city/region level.
4. Country centroid — mobile / VoIP / toll-free numbers are non-geographic and honestly resolve to country confidence.
5. Deterministic hash fallback — withheld/anonymous numbers get a stable position derived from the conversation ID; flagged hash, never cached, listed in the Unknown column and excluded from heatmaps and replay.

Confidence tiers: city · region · country · hash — the popup shows which tier produced the position. Results are LRU-cached (10,000 entries). Email originating-IP geolocation is deliberately disabled: it resolved the sending mail server (Office 365 / Gmail data centres), not the customer. Emails therefore sit in the Unknown column; IP geolocation remains available solely as an internal email diagnostic. A default region (ISO-2) can be configured for orgs that receive national-format numbers.

Panels & HUD

• KPI strip & gauges — active calls, agents online / on-queue / wrap-up, events-per-second and bandwidth gauges (updated every second), total interactions (24 h) counter.
• Live Queue Health board (Q) — per-queue agents total/idle, waiting conversations, assigned-but-unanswered alerts.
• Wrap-up codes panel — running tally of wrap-up codes, fetched 20 s after each call ends (agents need time to submit), with up to 3 retries at 5 s × attempt.
• Event log — the app’s own log lines with level colouring: connects, reconnects, rate-limit waits, circuit-breaker trips, geo misses, heatmap progress.
• 24-hour traffic chart (C) — hourly interaction volume by media type, rebuilt from analytics on connect in the background (capped at 500 pages = 50,000 conversations; beyond that the chart is flagged partial).
• Quality alerts — toasts (+ optional desktop notifications, N) when a call’s MOS < 3.5 (warn) / < 3.0 (alert) or RTP latency > 200 ms (warn) / > 400 ms (alert).

Heatmap

A density layer of up to 30 days of historical conversations. Pick a window (24 h / 7 / 14 / 30 days) and press ▶ Go:

• Go is cache-first — a build for the same window newer than the cache TTL (6 h by default, §5) renders instantly, and the event log says “served from cache (built N m ago)”. Shift+click Go forces a fresh pull from Genesys.
• A fresh build submits an async analytics details job, waits for Genesys to compile it (up to ~15 minutes), then pages through the results; a progress bar shows how far it has got.
• Points are binned to 3-decimal weighted centroids. Only city/region confidence points are plotted — country-centroid and hash positions would stack on one spot and fake a hotspot, so they are counted but excluded.
• If a results page fails mid-stream after data has flowed, the build renders what it has and is flagged partial rather than discarding everything.
• A build presumed hung (“running” > 20 min) is superseded automatically on the next Go.

Replay & capture

• Historical replay (X) — pick a past from/to window; the app fetches up to 2,000 conversations and animates them over the map on a time scrubber. Hash-fallback positions are excluded.
• JSON capture terminal — records every raw ingest event into a 2,000-entry ring buffer, tagged by source (live notification, analytics poll, analytics preload or REST poll), live-tails it and downloads as pretty-printed JSON — the tool of choice for “what did Genesys actually send?”.

Keyboard shortcuts

4How each org is kept separate

Each signed-in set of credentials gets its own isolated workspace: its own Genesys streaming connection, its own data and its own failure boundary. One org’s activity can never appear on another org’s map, and a problem in one workspace cannot affect another.

Signing in

• Credentials checked first. Your Client ID and Secret are checked with Genesys before anything else starts; a wrong secret or region fails straight away with Genesys’ own message.
• Shared by supervisors. People signing in with the same OAuth client share one workspace (so several supervisors can watch the same org); different clients always get separate workspaces.
• Credentials stay on the server. They are never written to storage and never sent to the browser.

Session lifecycle

• Logout — ends your session; if you were the last person using the workspace it is closed straight away and its Genesys notification subscriptions are removed. Other supervisors on the same workspace keep it.
• Tab closed, crash or laptop asleep — if no browser reconnects within a short grace period, the workspace is closed automatically. Page reloads and brief network blips reconnect well within the grace.
• Inactivity — sessions end after a period of inactivity.
• Service restarts — every workspace releases its Genesys subscriptions cleanly before stopping.

The live Genesys pipeline

• Connect sequence — OAuth → load all queues, Architect flows and inbound routes → create a notification channel and subscribe queue-conversation topics → resolve queue members and build a dedicated presence channel → start the reconcile polls → preload active conversations → go live. Progress is shown in the browser as it happens.
• Push first, poll as safety net — queue-conversation events drive the map in real time; periodic polls reconcile:

• Rate-limit friendly — every Genesys call is paced well under Genesys’ rate limits; the app slows down automatically when Genesys signals pressure, honours Retry-After on a 429, and refreshes its token once on a 401.
• Fault isolation — if analytics, presence or REST calls keep failing, that part pauses briefly and retries while the rest of the map keeps running.
• Notification channels — the main channel subscribes v2.routing.queues.{queueId}.conversations (extra channels are opened automatically for very large queue counts); the presence channel subscribes v2.users.{userId}.presence + v2.users.{userId}.routingStatus. Channels are kept alive, renewed when Genesys announces they are about to close, and rebuilt automatically after any reconnect.
• Zombie defence — ended conversations are held back for 2 min so lagging poll results can’t resurrect them; new calls get 90 s of grace (analytics indexing lags 10–30 s); a 5-minute sweep catches truly orphaned markers.

5Caching

Heatmap cache — per-window, 6 h, kept per org

• Per-window — builds are cached by window, so 24-hour, 7-, 14- and 30-day results coexist; asking for a window you built earlier renders instantly.
• Freshness — cached builds are reused for 6 hours by default. Historical density barely moves hour to hour, so cached builds stay useful for a long time. Shift+click Go bypasses the cache.
• Kept per org — the cache is kept separately for each org's credentials, so different orgs can never read each other’s points. It holds only aggregated location centroids with counts and build metadata — no identifiers.
• Self-heal — a build “running” for over 20 min is presumed hung and superseded by the next request.

Everything else is temporary

• Live data — conversation, agent and queue state is held only while your workspace is open and is wiped when it closes.
• Geolocation and name caches — short-lived lookups that avoid repeating work; withheld/anonymous (hash) positions are never cached.
• Recently ended calls / new-call grace — as described in §4.

6Genesys endpoints & permissions

Everything below is called with your org’s client-credentials token, paced as described in §4.

OAuth client permissions (client-credentials grant, read-only)

7Storage, privacy & security

• Credentials — checked with Genesys at sign-in and held on the server for your workspace only; never written to storage, never sent to the browser. The sign-in page remembers only Client ID + region in your browser as a convenience.
• Sessions — protected by a secure session cookie; sessions end after a period of inactivity.
• Live data — held only while your workspace is open. Logging out (or the workspace closing automatically) destroys it.
• The one per-org item kept — the heatmap cache (§5): aggregated location centroids and build metadata only, kept separately per org so different orgs can never read each other’s points. Clearing it is safe; the next build recreates it.
• Sensitive views — the JSON capture download and support diagnostics expose live org data (numbers, names, raw events). They require a signed-in session like everything else; redact before sharing output.
• Isolation — each org’s workspace is reachable only through its own signed-in session; different credential sets never share a workspace.
• Read-only against Genesys — see §1; the only deletions are of the app’s own notification-channel subscriptions.

8Technology

• Web application — sign-in, session handling and one isolated, server-side Genesys streaming workspace per org.
• Geolocation — phone-number parsing plus a bundled ~150-country prefix gazetteer, a curated North American area-code table and country centroids.
• Browser interface — a single-page live dashboard with clustered markers, a heatmap layer, a keyless basemap (§3) and dark/light/system themes.
• Monitoring — QVCCS monitors the service’s health so problems are spotted quickly.

9Troubleshooting

Sign-in fails: “Genesys OAuth rejected …”

Genesys refused the token exchange — wrong Client ID/Secret, a deactivated OAuth client, or the wrong region (tokens must be minted in the org’s home region). If the message says Genesys couldn’t be reached, try again shortly.

Sign-in fails: “The service is busy”

The service is handling as many orgs as it can at the moment. Try again shortly — workspaces close automatically soon after their users leave.

Sign-in fails because your workspace could not start in time

Anything half-started is cleaned up automatically. Try again; contact QVCCS support if it persists.

I came back to the tab and was logged out / “server shutting down”

Expected in three cases: (1) the session ended after a period of inactivity; (2) every browser connection was gone for longer than the disconnect grace (laptop sleep, network change) and the workspace closed; (3) the service was restarted. Sign in again — a fresh workspace starts in seconds; live state is deliberately temporary (the 24-hour chart rebuilds, the heatmap cache survives).

The map is empty even though we have calls

Check the connect progress reached “connected” and the queue and flow counts look sensible. Then verify the OAuth permissions (§6): missing analytics or notification permissions produce a connected-but-silent map. Finally check division scope — the OAuth client’s roles must cover the divisions that own your queues. QVCCS support can run a visibility check that pinpoints the gap.

“Bad gateway” or a blank page after leaving the tab open a long time

Your workspace closed while the tab stayed open. Reload — you will land on the sign-in page. If it keeps happening for several users, contact QVCCS support.

Event log shows “⏳ 429 … Retry in Ns” or “pressure mode”

The app brushed the Genesys rate limit and backed off automatically, honouring Retry-After; data continues after the wait. Frequent 429s usually mean the OAuth client is shared with other integrations — give the map its own client.

“⛔ Circuit analytics/presence/rest: open after N failures”

One kind of Genesys call kept failing, so the app paused it and will retry after a short cool-down. The rest of the app keeps running; presence counts may freeze briefly. Repeated trips indicate Genesys-side trouble or permission errors.

Could this app hit the Genesys notification-channel limits?

Genesys allows ~20 channels per OAuth client (oldest evicted) and ~1,000 topics per channel. The app uses one main channel, one presence channel and extra channels only for very large queue counts, and every teardown deletes its subscriptions. Several workspaces sharing one OAuth client multiply channel usage — another reason for a dedicated client.

A marker is in the wrong place / mid-ocean / in the Unknown column

Geolocation is only as good as the number: mobile and non-geographic numbers resolve to a country centroid; withheld/anonymous numbers get a deterministic hash position, listed in the ⊘ Unknown column and excluded from heatmaps. The popup’s geo method/confidence row tells you which tier fired. A default region can be configured for orgs that receive national-format numbers.

Why do emails never get a real location?

Deliberate. Originating-IP lookups from email headers resolved the sending mail server (Office 365 / Gmail data centres), not the customer — misleading, so live email geolocation is disabled and emails stay in the Unknown column.

The heatmap renders instantly with slightly old data

That’s the per-window cache (6 h, §5) — the event log line says when the build was made. Shift+click Go forces a fresh pull.

Heatmap takes ages or comes back “partial”

Large windows walk an async analytics job (up to ~15 minutes) plus paged downloads; 30-day builds on busy orgs are slow by nature. “Partial” means a results page failed after data had started flowing — what was fetched is rendered. Only city/region-confidence points are plotted, so the plotted count is always below the scanned count.

The basemap suddenly looks different (standard OSM colours)

The main basemap kept failing to load and the map switched to the OpenStreetMap fallback for this session (a warning appears in the event log). Usually transient — reload to try the main basemap again. If it happens everywhere permanently, tell QVCCS support.

Calls flicker back after ending / appear late

Genesys analytics indexing lags 10–30 s. The app holds ended conversations back for 2 minutes, gives new calls 90 s of grace, and sweeps stale markers every 5 minutes. Brief lateness on quiet channels (chat/email arriving via poll rather than push) is normal.

Does closing my laptop lid overnight leave anything running?

No. The live connection drops when the machine sleeps; after the disconnect grace the workspace closes, its Genesys subscriptions are removed and the session ends. Next morning you sign in afresh.

Where are credentials and data stored?

Credentials are held on the server for your workspace only — never written to storage, never in the browser. Live data exists only while your workspace is open. The only thing that outlives a session is the per-org heatmap cache of anonymous aggregated centroids (§5, §7).