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
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
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.
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).
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.
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)
Card
What it shows
Summary
Direction 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 counters
Tiles 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 journey
The 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 — timeline
Every 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 replay
Loaded on demand — see below.
Audio quality
Per 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 data
The 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 & segments
The 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 data
A 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
Press ▶ Load flow replay. The app runs the four-step pipeline in §5 (usually a few
seconds); the button becomes ↻ Reload for retries.
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.
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…).
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.
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
Metric
Excellent
Good
Fair
Poor
Bad
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
Endpoint
Used for
POST
login.<region>/oauth/token
Client-credentials sign-in; token lazily refreshed ~60 s before expiry and once on any 401
GET
/api/v2/organizations/me
Org name for the header badge (best-effort)
GET
/api/v2/analytics/conversations/{id}/details
The authoritative conversation detail record — required
GET
/api/v2/conversations/{id}
Best-effort live object: recording flags, ANI/DNIS display, participant attributes
ID → name resolution (≤150 IDs per type, cached per session)
POST
/api/v2/flows/instances/query?pageSize=200
Find flow execution instances by ConversationId (a read query)
POST
/api/v2/flows/instances/jobs?expand=dataActions
Start 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)
GET
presigneddownloadUri
The 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)
GET
presignedmediaUri
Prompt audio — played directly by the browser, never proxied
OAuth scopes & role permissions
OAuth scopes & role permissions
Scope
Needed for
analytics:readonly
Required — the conversation detail record. Without it every analysis 403s.
conversations:readonly
Live object: recording flag, participant attributes, display names.
routing:readonly
Queue / wrap-up / skill names.
users:readonly
Agent names.
architect:readonly
Flow 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:readonly
Division names.
organizations:readonly
Org 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.
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.