Live Call Map: every active Genesys Cloud conversation on a world map, placed with care

Picture a multinational service desk at 07:30 UK time. Asia-Pacific is winding down, Europe is ramping up, and North America is asleep – or is it? A storm on the east coast, a mobile network outage in one country, a marketing email that lands in another time zone: each shows up first as a change in where calls are coming from. Tables of queue statistics will tell you the volume. They will not show you the shape.

Live Call Map paints that shape. It subscribes to your organisation’s notification streams and puts a clustered marker on a world map for every active conversation – voice, chat, email, messaging, callback, bot, workflow, co-browse, video and social – coloured by media type and state, with long-waiting calls pulsing faster. Around the map sit live agent presence counts, a Queue Health board, a wrap-up code tally, a 24-hour traffic chart, quality alerts, historical replay and a geographic heatmap of up to 30 days.

This is the part we are most careful to explain, because a map invites people to believe what it shows. Live Call Map never knows where a person physically is. It has no device location and no GPS. Each position is derived only from a telephone number: the caller’s number (ANI) for inbound conversations, or the dialled number (DNIS) for outbound. The map shows where that number is registered, as best a number can say, and every marker’s popup states the method and the confidence tier that produced it.

The lookup runs in order and the first match wins. North American numbers use a curated area-code table that maps to city centroids. For other numbers, an open-source phone-number library decides whether the number is geographic – a fixed line – and if so a bundled gazetteer covering around 150 countries gives a city-level position, with curated sub-country prefixes filling gaps at city or region level. Mobile, VoIP and toll-free numbers are non-geographic, so they resolve only to a country centroid and are labelled with country confidence. Results are cached, up to 10,000 entries.

Withheld and anonymous numbers cannot be located at all. Rather than invent a place, the app gives them a stable placeholder derived from the conversation ID, flags them as hash, lists them in an “⊘ Unknown” column beside the map, never caches them and excludes them from heatmaps and replay. Emails land in that Unknown column too, by design. We tried geolocating the originating IP in email headers and found it located the sending mail service’s data centre, not the customer – misleading, so live email geolocation is switched off. Organisations that receive national-format numbers can set a default country.

Inside each worker, the connect sequence loads queues, Architect flows and inbound routes in parallel, then creates a notification channel subscribed to v2.routing.queues.{queueId}.conversations for every queue. Large organisations get overflow channels automatically, because a channel is limited to 1,000 topics. A second, dedicated presence channel subscribes v2.users.{userId}.presence and v2.users.{userId}.routingStatus for queue members, in batches. Active conversations are preloaded through POST /api/v2/analytics/conversations/details/query, and from then on the queue-conversation events drive the map in real time.

Push is fast, but push alone can miss things, so REST pollers reconcile in the background: an analytics active-conversation poll every eight seconds, a users poll every ten seconds that re-seeds presence from /api/v2/users?expand=presence,routingStatus, queue observations every 15 seconds, and a full reconcile every five minutes that picks up new queues, flows and agents. An optional REST poll catches calls still in the IVR, before they reach any queue, when the client has the permission for it.

Two kinds of politeness keep this healthy at scale. Every Genesys call flows through a rate-limit pacer that reads the platform’s rate-limit response headers, slows down as it approaches the ceiling, and honours Retry-After on a 429. Circuit breakers isolate analytics, presence and REST failures so one struggling area cannot take the map down. And because analytics indexing lags slightly behind the live stream, ended conversations are held as tombstones for two minutes so a late poll result cannot bring a finished call back to life.

A streaming pipeline of channels, pollers and caches is substantial per organisation, so the defining design decision was process isolation. A front door validates each sign-in directly against Genesys OAuth, before anything else is created, and then starts one worker process per credential set – region plus OAuth client. Each worker owns its own Genesys connection, memory and crash domain. Two supervisors who sign in with the same OAuth client share a worker; different clients never share a process, so one organisation’s data can never appear in another’s view.

Lifecycle is managed for the user. Logging out tears the worker down at once if it was the last session, and the logout overlay narrates the real steps as the worker releases its notification subscriptions. Closing the tab without logging out is also safe: when every browser connection to a worker has gone and nothing reconnects within a two-minute grace, the worker is reaped and its sessions purged. A laptop closed overnight does not leave a pipeline running.

The heatmap shows the density of up to 30 days of conversations. A fresh build submits an asynchronous analytics conversation details job, polls its state every four seconds and cursor-pages the results, with a progress bar driven by a quick size probe. Because historical density barely moves hour to hour, completed builds are cached per window – 24 hours, 7, 14 or 30 days can coexist – for six hours by default. Pressing Go is cache-first and the event log says when the build was made; Shift+click forces a fresh pull from Genesys.

Resilience was designed in. If a results page fails after data has started to flow, the build renders what it has and is flagged partial rather than thrown away, and a build presumed hung after 20 minutes is superseded by the next request. Historical replay animates up to 2,000 past conversations across the map on a time scrubber. For support engineers, a capture terminal records raw ingest events, tagged by source, into a 2,000-entry ring buffer that can be downloaded as JSON – the quickest way to answer “what did Genesys actually send?”.

Caller numbers are personal data, and a map of them deserves care. Live Call Map is strictly read-only against Genesys: it never modifies conversations, queues or users, and its only deletes are of its own notification subscriptions. Live data lives in worker memory and an ephemeral per-worker cache that is deleted when the worker starts and again when it shuts down. Credentials are never written to disk or sent to the browser.

The only file that outlives a session is the heatmap cache, and it holds aggregated latitude, longitude and count centroids with build metadata only – no numbers, names or conversation IDs – namespaced so that different organisations can never read each other’s points. Diagnostic outputs that do contain live organisation data sit behind the session like everything else, and the guide tells engineers to redact before sharing. Positions are approximate by construction, and we say so on every marker.

Genesys Cloud’s own views remain the system of record for this data. The Interactions view lists conversations with filters including ANI, DNIS, direction, waiting and interacting states and MOS, over ranges of up to 31 days. The Queues Activity Detail view gives real-time queue operations: waiting and interacting conversations, agent statuses including Not Responding, service level, and manual assignment. Live Call Map does not replace these; it adds a geographic lens on the same conversations, live presence and queue health in one place, and quality toasts when MOS drops below 3.5 or RTP latency passes 200 ms.

The app is a product of the QVCCS lifecycle: supervisors’ questions captured as requirements, an architecture decision record for the worker model, a privacy and data-protection design reviewed by design authority, and negative-path testing of reaping, rate limits and division scope. Our Solution Architects, Senior Developers, Systems Integration Testers and Support Engineers built and proved it together, backed by the whole practice.