QVCCS App Suite · Diagnostics & troubleshooting

Conversation Analyser

Single-conversation forensics for Genesys Cloud CX. Paste one conversation ID and the tool reconstructs the entire interaction — a caller & agent swim-lane, a plain-English timeline, timings and counters, per-leg audio-quality scoring, the custom participant data your flows attached, and an on-demand step-by-step replay of every Architect flow the call traversed, with click-to-play prompt audio. GUIDs become names; the raw record stays one click away.

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

  • single-conversation forensics
  • one conversation at a time
  • swim-lane + timeline
  • flow execution replay
  • prompt playback
  • audio-quality scoring
  • no database
  • strictly read-only

Security at a glance

Conversation Analyser

Read-only

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; each conversation is fetched live per request and never retained
AI
No AI
Exports
JSON download of the full raw record
Genesys Cloud permissions
analytics:readonly (required); optional conversations, routing, users, architect (with flow-instance and prompt view), authorization and org read

Compare every app

1What it is

Conversation Analyser answers the question “what exactly happened on this one call?”. An operator signs in with a Genesys Cloud OAuth client-credentials grant (region + client ID + client secret), pastes a single conversation ID, and the app pulls everything Genesys knows about that interaction and renders it as a forensic report:

  • Caller & agent journey — a swim-lane, one row per participant, every segment (IVR, queue, ring, talk, hold, transfer, wrap-up) drawn as a colour-coded bar on a shared clock.
  • Timeline — the same story as a narrative: clock time, offset from start, durations, key events and disconnect reasons in plain English.
  • Timings & counters — IVR, queue wait, ring, talk, hold, after-call work, distinct agents and transfers, preferring the record’s t*/n* metrics with segment-sum fallbacks; every remaining raw metric shown as a badge.
  • Audio quality — MOS, R-factor, max latency and packet loss per participant and media window, each rated on fixed thresholds (§4).
  • Flow execution replay — an on-demand flowchart of each Architect flow (IVR / bot / in-queue) the call passed through, from the Historical Flow Execution Data API: prompts played, DTMF pressed, decisions taken, data actions run, variables set — with click-to-play audio for prerecorded prompts.
  • Participant data — the custom attributes flows attach with Set Participant Data (account number, intent, screen-pop URL…), fetched from the live Conversations API because the analytics record omits them.
  • Names, not GUIDs — user / queue / wrap-up / flow / division / skill IDs resolved to real names, best-effort and cached; unresolvable IDs fall back to the raw GUID.
  • Raw data — the complete payload (analytics detail + live object + name maps) as pretty-printed JSON with copy and download buttons.

Typical uses: complaint investigation (“why was this caller on hold for nine minutes?”), audio-quality triage (“which leg had the packet loss?”), routing verification (“what did the caller actually press, and did the IVR send the call to the right queue?”) and agent-journey QA (transfers, wrap-up codes, after-call work).

Read-only by design. Every Genesys call the tool makes is a read — the only POSTs are the flow-instance query and the download-job creation, which create no org data. Credentials are held on the server and never sent to the browser; the browser never holds a Genesys token.

Sibling tools: Conversation Detail is the bulk counterpart — it exports every conversation over a date range; use it to find the interesting conversation, then this tool to dissect it. Flow Journey grew out of this app’s flow-replay pipeline and renders the same execution data as a pictorial journey.

2Quick start

  1. One-time: create the OAuth client — Genesys Cloud Menu > IT and Integrations > OAuth → Add client, grant type Client Credentials, a read-only role. Minimum scope analytics:readonly; add the optional scopes in §5 for names, participant data, flow replay and prompt audio.
  2. Sign in — open the app, pick your region (the hint under the picker shows the Genesys API domain it maps to), paste client ID + secret. Credentials are validated against Genesys immediately; the login page remembers your client ID and region (never the secret).
  3. Analyse — paste a conversation ID (a UUID like 0a1b2c3d-4e5f-6789-abcd-ef0123456789) into the box and press Analyse — or open a deep link containing the ID. The report renders in a few seconds.
  4. Go deeper — press ▶ Load flow replay in the Flow execution replay card to reconstruct the IVR step-by-step; click any ▶ prompt chip to hear what the caller heard.

No credentials to hand? Open the preview from the sign-in page (no sign-in needed) or press Load demo after signing in — both render a bundled synthetic conversation (inbound call → IVR → queue → agent → hold → blind transfer → wrap-up, with a deliberate mid-call audio-quality dip) that exercises every card, including a two-instance flow replay.

3UI walkthrough

Sign-in page & header

  • Login page — a region picker (the canonical 14-region Genesys list, flag-labelled, value = API domain), client ID and client secret fields, and a link to this guide. Sign-in errors are shown above the form. The last client ID + region are remembered in your browser; the secret is never stored in the browser.
  • Top bar — the CA brand mark, then on the right: an org badge (your organisation’s name, resolved best-effort at sign-in), a region badge, the 📖 Guide button (opens this manual in a new tab) and Sign out, which ends the session immediately.
  • Query card — one Conversation ID input (monospace, strictly validated as an 8-4-4-4-12 hex UUID, whitespace trimmed), the Analyse button and a Load demo button. Any API answer of 401 mid-session bounces the browser back to the login page.
  • Deep links — a link carrying a conversation ID pre-fills the box and analyses immediately (handy for pasting into tickets).

The result cards (top to bottom)

The result cards (top to bottom)
CardWhat it shows
SummaryDirection badge (inbound/outbound), the conversation ID with a Copy ID button, media types, recorded badge (from the live object), flagged badge with reason, duration, start/end timestamps, participant count, From (ANI) / To (DNIS), and the minimum MOS across all legs with its quality colour.
Timings & key countersTiles for IVR/flow time, ACD/queue wait, ring (alert), talk, hold (with hold count), after-call work, distinct agents and transfers. Values prefer the record’s metrics (tIvr, tAcd/tWait, tAlert, tTalk, tHeld, tAcw, nTransferred + blind/consult variants…) and fall back to summing segment durations. Every remaining raw metric appears as a badge below the tiles.
Caller & agent journeyThe swim-lane: one lane per participant (customer/external first, then IVR, ACD, agents), each segment a colour-coded bar on a shared time axis. Hovering a bar shows a tooltip with exact times, duration, queue, wrap-up code and disconnect reason.
What happened — timelineEvery segment in chronological order, phrased plainly (who did what), with clock time + offset from the start, durations, and an end-of-call disconnect summary.
Flow execution replayLoaded on demand — see below.
Audio qualityPer participant & media window: MOS, R-factor, max latency and packet loss, each with a rating pill (excellent → bad) and meter, plus a packet-detail line (received / invalid / discarded). Thresholds are printed under the card and in §4.
Participant dataThe custom attributes attached to each participant during the call — sourced from the live Conversations API (the analytics record has none), so it needs the conversations scope and the conversation to still be within that API’s retention.
Participants, sessions & segmentsThe full structured breakdown: purpose, resolved name, each session’s media type, ANI/DNIS, segment list, requested routing users/skills and wrap-up codes — IDs resolved to names where possible.
Raw dataA collapsible details panel with the complete payload (analytics detail + resolved names + live object) pretty-printed, Copy JSON and Download JSON (saved as conversation-<id>.json) buttons, and a live: … badge whenever the live object was unavailable.

Flow-replay screen

  1. Press ▶ Load flow replay. The app runs the four-step pipeline in §5 (usually a few seconds); the button becomes ↻ Reload for retries.
  2. Each Architect flow instance the call traversed renders as its own card (flow name + type — e.g. an inbound IVR, then the in-queue flow), earliest first, each headed by a step counter and a Compact view / Detailed view toggle.
  3. The flowchart is one shaped, colour-coded node per executed step — audio, menu, switch/decision, data-table lookup, set-data, call-task, transfer, terminators — showing the spoken text / DTMF pressed / lookup result / variables set, per-step clock time and dwell, and nested called-task sub-flows. The label on each connector is the branch the call actually took (Found / Not found / Timeout / the digit pressed…).
  4. Play what the caller heard — steps that played a prerecorded prompt show a ▶ prompt-name chip. Clicking it resolves the prompt live from the Architect prompt library and plays the recording right in the step — one player per language that has audio, with the transcript underneath when one is stored. Dynamic TTS lines have no recording (the trace already shows their spoken text) and Genesys system prompts (hold music, beeps) aren’t in the user-prompt library, so neither gets a chip. Playback needs architect:userPrompt:view; without it the chip explains what’s missing and the rest of the replay is unaffected.
  5. What to look for: menu retries (the same collect-input node repeating), data-action Failure branches, what each variable was set to, and the transfer target at the end. Raw instance data (collapsible, per instance) holds the untouched execution document with a Copy JSON button.

Demo & preview modes

  • Load demo (button beside Analyse) — loads the bundled synthetic conversation: inbound call → IVR (36 s) → Support — Tier 1 queue (42 s wait) → agent Sarah (15 s ring), one 45 s hold → blind transfer to David → wrap-up, with a deliberate mid-call audio-quality dip. In demo mode the flow-replay button loads a synthetic replay (two instances: Main Contact Centre IVR + Default In-Queue Flow) instead of the live pipeline, and prompt chips explain that demo prompts have no real audio. A banner reminds you the data is synthetic.
  • Preview mode (no sign-in) — the same UI with the header showing Demo preview · synthetic data; the demo loads automatically and the Sign out button becomes Sign in →. No live Genesys call is possible from preview.

4Domain concepts

The analytics detail record vs the live conversation object

The report is assembled from two Genesys views of the same conversation:

  • Analytics conversation detail record (GET /api/v2/analytics/conversations/{id}/details) — the authoritative source, retained for months: participants → sessions → segments → metrics → media-endpoint stats. If this 404s there is nothing to analyse and the request fails.
  • Live conversation object (GET /api/v2/conversations/{id}) — best-effort extra, retained far more briefly: recording flags, display names, ANI/DNIS and the custom participant attributes the analytics record omits. Failures are non-fatal — the error is shown as a badge and the analytics-based cards render regardless.

Within the detail record: a participant is each party or system role on the call (customer, IVR, ACD, agents); each participant has sessions (media legs) made of segments — typed time slices (ivr, queue, alert, interact, hold, wrapup…) that the swim-lane and timeline draw. Metrics are the aggregate t* duration / n* count numbers Genesys emits per session.

Flow execution data (the replay’s source)

Architect’s Historical Flow Execution Data records the step-by-step path a call took through a flow. Three properties shape what the replay can show:

  • Opt-in per flow — the flow must have “capture execution data” enabled in Architect settings when the call ran. Non-capturing flows legitimately return nothing.
  • ~10-day retention — older calls return no instances even for capturing flows.
  • One instance per flow traversed — a call through a main IVR and an in-queue flow yields two instances; the replay sorts them chronologically (the jobs API can return them out of order).

Each downloaded document’s ordered step trace lives at data.flow.execution[] as single-key wrapper objects whose key names the step type (startedFlow, actionPlayAudio, actionSwitch, menuMenu, actionDataTableLookup, actionCallTask, actionTransferToAcd, endedFlow, …); the renderer normalises each key into a typed node.

Real traces only. Prompts and DTMF shown in the replay always come from the actual execution trace — never reconstructed from static flow configuration. Prerecorded prompts appear in a trace’s audioItems[] as promptName + promptId (a UUID = a user prompt, resolvable to audio); TTS items carry their text; pseudo-IDs like __on_hold_music__ are system prompts and cannot be resolved.

Audio-quality scoring

Scores come from each session’s media-endpoint stats in the analytics record. Ratings use fixed thresholds:

Audio-quality scoring
MetricExcellentGoodFairPoorBad
MOS (1–5)≥ 4.3≥ 4.0≥ 3.6≥ 3.1< 3.1
R-factor (0–100)≥ 90≥ 80≥ 70≥ 60< 60
Max latency—≤ 150 ms≤ 300 ms≤ 500 ms> 500 ms
Packet loss—≤ 0.5 %≤ 1.5 %≤ 3 %> 3 %

Packet-loss % is computed as (invalid + discarded) / (received + invalid + discarded). Latency and loss have no “excellent” tier — ≤150 ms / ≤0.5 % is simply good. Non-voice legs (chat, email, callback) carry no RTP stats and show “—”.

Reading the card: bad MOS with high loss on the customer leg points at the caller’s network; the same on the agent leg points inside your estate.

Name resolution & enrichment

The app walks the detail record, collects every resolvable ID by type — user, queue, wrap-up, flow, division, skill, up to 150 per type — and resolves each against the matching Genesys endpoint a few lookups at a time, caching results per session. Two free enrichment passes then fill gaps the API could not resolve (missing scope, deleted entity):

  • a flow that transferred directly to a user carries that user’s name in its own transferTargetName — so the handler resolves even without the users scope;
  • the live conversation object names its participants.

API-resolved names always win; anywhere no name is found the raw GUID is shown, so the tool stays fully usable with only analytics:readonly.

5Genesys endpoints & permissions

Every Genesys call the app makes, in the order a typical analysis uses them:

Genesys endpoints & permissions
EndpointUsed for
POSTlogin.<region>/oauth/tokenClient-credentials sign-in; token lazily refreshed ~60 s before expiry and once on any 401
GET/api/v2/organizations/meOrg name for the header badge (best-effort)
GET/api/v2/analytics/conversations/{id}/detailsThe authoritative conversation detail record — required
GET/api/v2/conversations/{id}Best-effort live object: recording flags, ANI/DNIS display, participant attributes
GET/api/v2/users/{id} · /api/v2/routing/queues/{id} · /api/v2/routing/wrapupcodes/{id} · /api/v2/flows/{id} · /api/v2/authorization/divisions/{id} · /api/v2/routing/skills/{id}ID → name resolution (≤150 IDs per type, cached per session)
POST/api/v2/flows/instances/query?pageSize=200Find flow execution instances by ConversationId (a read query)
POST/api/v2/flows/instances/jobs?expand=dataActionsStart the download-preparation job (instance IDs, capped at 50)
GET/api/v2/flows/instances/jobs/{jobId}Poll the job every 800 ms, up to 30 tries (~24 s)
GETpresigned downloadUriThe actual step trace (fetched without a bearer token)
GET/api/v2/architect/prompts/{promptId}Prompt click-to-play: per-language resources with short-lived presigned mediaUris (cached briefly)
GETpresigned mediaUriPrompt audio — played directly by the browser, never proxied

OAuth scopes & role permissions

OAuth scopes & role permissions
ScopeNeeded for
analytics:readonlyRequired — the conversation detail record. Without it every analysis 403s.
conversations:readonlyLive object: recording flag, participant attributes, display names.
routing:readonlyQueue / wrap-up / skill names.
users:readonlyAgent names.
architect:readonlyFlow names, flow execution replay (role also needs Architect › Flow Instance › Search and › View — architect:flowInstance:search/:view) and prompt playback (Architect › User Prompt › View — architect:userPrompt:view).
authorization:readonlyDivision names.
organizations:readonlyOrg name in the header banner.

The tool works with analytics:readonly alone — the other scopes only add names and the optional extras. Scopes are minted into the token at sign-in: after granting a permission, sign out and back in.

6Storage, privacy & security

  • No database, nothing kept — nothing is stored persistently. Sessions and name caches exist only while you are signed in; if the service restarts, users simply sign in again. Conversation payloads are fetched live per request and never retained.
  • Credential handling — signing in performs the client-credentials grant with Genesys; the credentials and bearer token are held on the server and never sent to the browser, which holds only a secure session cookie.
  • Token refresh — tokens are refreshed shortly before they expire, and once (with a retry) whenever Genesys answers 401.
  • Sessions — sessions end after a period of inactivity; signing in again with the same region + client ID replaces your older session. Sign out ends the session at once.
  • Browser storage — exactly one convenience item: the login page remembers your last client ID + region. The secret is never stored in the browser.
  • Read-only posture — the only Genesys POSTs are the flow-instance query and the download-job creation, both read operations; the tool cannot modify anything in the org.
What leaves the service: nothing except the Genesys API calls themselves. Prompt audio and flow-trace downloads use short-lived presigned URLs (audio goes straight to the browser); the app pages load their webfonts from Google Fonts.

7Technology

  • Web application — deliberately small: sign-in, Genesys orchestration, name resolution and the flow-replay pipeline in one compact service, with no database.
  • Browser interface — one page renders every card — swim-lane, timeline, quality meters, flowchart — in your browser from a single result.
  • Analysis pipeline — one request fetches the analytics detail record (fatal if missing), the best-effort live object and ID → name resolution, then returns one result. Flow replay runs on demand through the asynchronous pipeline: query instances → start job → poll (up to ~24 s) → download the presigned traces. Prompt audio resolves per click with a short cache because the media URLs are short-lived.
  • Demo data — bundled synthetic conversations, structurally faithful to the live shapes so every card renders.

8Troubleshooting

Every message below comes from a real failure mode.

“That does not look like a conversation ID (expected a UUID…)”
The input isn’t an 8-4-4-4-12 hex UUID — often a stray character, or a queue/participant ID pasted by mistake. Copy the conversation ID exactly; surrounding whitespace is trimmed for you.
“No analytics detail record found for that conversation ID in this org / region.”
The ID doesn’t exist in the org you signed into — usually the wrong region at login, an ID from another org, or a typo. Very recent calls can also take a short while to appear in analytics.
“Access denied by Genesys. The OAuth client needs the analytics:readonly scope…” (403)
The OAuth client lacks analytics:readonly (or its role lacks the analytics conversation-detail view permission). Add it, then sign out and back in — scopes are minted into the token at sign-in.
Flow replay: “Access denied. Reading flow execution data needs… architect… flowInstance:search / view.” (403)
Missing architect/architect:readonly scope, or the role lacks Architect › Flow Instance › Search / View. Grant both, sign out/in, retry — everything else keeps working without it.
Flow replay: “No flow execution data for this conversation.”
The flow didn’t have capture execution data enabled when the call ran, the call is older than the ~10-day retention, or it never traversed an Architect flow. Enable capture in the flow’s Architect settings for future calls; past uncaptured calls cannot be recovered. The rest of the analysis is unaffected.
Flow replay: “The data-preparation job didn’t finish in time — showing flow metadata only.”
Genesys’ download job outlived the ~24 s polling window. Press ↻ Reload — it is usually ready on the second attempt.
Prompt chip: “Playing prompts needs the Architect › User Prompt › View permission…”
Grant architect:userPrompt:view to the OAuth client’s role and sign out/in. A 404 on a chip means the prompt has been deleted from the org since the call ran. Chips never block the rest of the replay.
Suddenly redirected to the login page
Your session ended: after a period of inactivity, because the service was restarted, or because the same client ID signed in elsewhere. Sign in again — the page pre-fills your client ID and region.
“The service is busy – try again shortly.”
The service is handling as many sign-ins as it can. Try again shortly — or sign in with a client ID + region already in use, which replaces the older session.
Badge “live: HTTP 404” in Raw data; Participant data card empty
The conversation has aged out of the live Conversations API (it keeps far less history than analytics), so recording flags and custom attributes are unavailable. Expected for old calls — the analytics-based cards are complete regardless.
Names show as raw GUIDs
The optional read scope for that entity type is missing (§5), the entity was deleted, or more than 150 distinct IDs of one type appeared (resolution is capped per type). Handlers reached by a direct flow→user transfer still resolve without users:readonly.
Sign-in fails with a Genesys OAuth error
Wrong client ID/secret, not a Client Credentials grant, a disabled client, or the wrong region (credentials are per-org; orgs are per-region). The exact Genesys error_description is shown on the login page.
Min MOS shows “—” / audio card sparse
No media-endpoint stats on the record — normal for chat/email/callback legs; voice legs of the same call still score.
Demo banner won’t go away
You’re in demo mode (or in preview). Paste a real conversation ID and press Analyse; from preview, use the Sign in → button.

FAQ

  • Does the tool change anything in Genesys? No — every call is a read; the only POSTs are the flow-instance query and download-job creation, which create no org data.
  • Where are my credentials kept? Only on the server, for as long as your session lasts; sessions end after a period of inactivity. Your browser holds a session cookie and the optional client-ID/region hint — never the secret.
  • Why do two flow instances appear for one call? Each Architect flow the call traversed (e.g. main IVR, then the in-queue flow) captures its own execution instance; the replay shows them in execution order.
  • Can several people use it at once? Yes — each session has its own credentials, token and caches.

QVCCS Conversation Analyser — single-conversation forensics for Genesys Cloud CX. Strictly read-only against the Genesys APIs; no database — every report is fetched live per request.

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 Conversation Analyser 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.

Explore the tiers

Last reviewed

Questions about what you have read?

Clients, partners and people introduced to us can reach the specialists behind our applications and articles directly.

Who to contact