Conversation Detail

1What it is

Conversation Detail answers the question “give me everything that happened between these two points in time”. Sign in with a Genesys Cloud OAuth client-credentials grant, optionally tick one or more divisions, pick a start and end date & time (UTC), and the app collects every matching conversation as a complete analytics conversation detail record — plus two enrichment passes the analytics API cannot provide on its own:

• Participant attributes — the key/values your flows attach with Set Participant Data (account numbers, intents, verification outcomes…), fetched per conversation from the live conversations API and merged into each record. System junk keys are filtered out so exports stay usable (§4).
• IVR flow variables (opt-in per run) — every variable each Architect flow set with its final value, plus each DTMF input the caller made with the value entered per attempt and failure counts — ideal for spotting entry struggles at scale.

Agent, queue, wrap-up, flow, skill and division ids are resolved to human-readable names. The whole dataset is stored with the collection and downloads as a single JSON file (full nested records + a meta summary) or a flat, filterable Excel workbook — one row per conversation, one column per attribute and per flow variable.

Typical uses: building datasets for reporting and reconciliation, auditing what the IVR collected across thousands of calls, exporting SetParticipantData to match against a CRM, and shortlisting the interesting conversation ids to dissect one-by-one in the sibling Conversation Analyser tool.

2Quick start

1. One-time: create the OAuth client — Genesys Cloud Menu > IT and Integrations > OAuth → Add client, grant type Client Credentials, attached to a read-only role. analytics:readonly is the only hard requirement; the other scopes in §5 add attributes, names, divisions and the IVR option.
2. Sign in — pick your region (the dropdown shows the Genesys API domain), paste the Client ID + Secret. The last Client ID and region (never the secret) are remembered in your browser for next time.
3. Scope and pick the range — optionally tick divisions; set start/end date + time (UTC, inclusive) or hit a preset (Today · Yesterday · Last 7 days · Last 30 days). Optionally tick IVR flow variables — keep the range small for that (§4).
4. Collect — watch the phases stream live: submitting → Genesys preparing → scanning → harvesting participant details → (flow data) → resolving names. The run is a detached background job: refresh, navigate away or lose the network freely — the page reattaches. Only the Cancel button stops it.
5. Download — Download Excel for spreadsheet analysis, Download JSON for the complete raw records. Finished collections stay downloadable, including after a service restart or a re-login with the same OAuth client.

3The collector UI

Sign-in page

Region dropdown (the 14 Genesys regions), Client ID and Client Secret. The hint under the dropdown shows the resulting Genesys API domain. A failed sign-in shows the Genesys error_description verbatim. On submit your browser remembers the Client ID and region to pre-fill next time — the secret is never stored anywhere in the browser.

Collection form

• Topbar — org and region pills (org name fetched best-effort from /api/v2/organizations/me), the Delete data button (label shows the collection count, tooltip the size), the 📖 Guide link (this page) and Sign out.
• Divisions — multi-select checkboxes, home division listed first and marked (home), with Select all / Clear and a live hint (“N selected — job scoped to…” / “All divisions”). Leave all unticked for the whole org. If the OAuth client cannot list divisions the panel degrades to “all divisions” and collections still work unfiltered.
• Range — start/end date + time, inclusive, UTC (defaults 00:00 → 23:59, both dates defaulting to today). Preset buttons fill the dates and reset the times. Ranges longer than the window size (default 7 days) are split into windows automatically, one async Genesys job each.
• IVR flow variables — opt-in checkbox per run. Adds a flow-instance query per flow-traversing conversation plus download jobs, so it is slower — best on a small range or one division. Needs architect:readonly and per-flow “capture execution data”; if the scope is missing the run continues with flow data disabled and records the reason.

Live progress

• Metric tiles — Conversations (relabelled Kept when division-filtering, when a Scanned tile also appears), Details harvested, Window x/y, and the live API req/s the pacer is currently allowing.
• Status line + progress bar — per-phase text; the bar is determinate wherever possible, driven by a best-effort totalHits probe per window and by per-conversation harvest ticks.
• Journal — a scrolling log console (info / success / warn / error lines). The last 300 lines per job are kept and replayed on reconnect.
• Detached runs — the browser tab remembers the running job; a full page reload reattaches and reopens the live progress. Dropped connections reconnect automatically and the retained state is replayed — a dropped connection never cancels a run. Cancel is explicit and deletes the partial file.

Results & downloads

• Badges — done, truncated (hit the 250k cap) or cancelled — partial.
• Chips — conversations, participants, segments, distinct agents / queues / flows.
• Breakdown tags — actual first→last start range, division scope with kept-of-scanned counts, attribute-column and IVR-variable-column counts (with the caller-input vs lookup split), flow instances downloaded vs found, cache-reuse counts, attributes-enriched ratio, and per media-type / direction / participant-purpose totals.
• Preview table — the first 100 conversations: id, start (UTC), direction, media, participant count, purposes, first agents, queue count.
• Downloads — Download Excel and Download JSON, both date-stamped.

Excel export layout

A single Conversations sheet, one row per conversation, header row frozen and bold. Column groups, left to right:

1. Fixed conversation columns — Conversation ID · Start (UTC) · End (UTC) · Duration (s) · Direction · Media types · Participants · Purposes · Agent names · Agent IDs · Queue names · Queue IDs · Wrap-up names · Wrap-up codes · Flow names · Division names · Customer ANI · Customer DNIS · External contact IDs · Attributes resolved (yes/no).
2. IVR columns (only when flow data was collected) — IVR flows · IVR inputs (a readable per-input trace showing every attempt in order, e.g. Account Number: ∅ → 703986 (2 tries, 1 failed)) · IVR retries · IVR max attempts.
3. One column per flow variable — caller-input / author-assigned (“business”) variables first, then data-lookup outputs; alphabetical within each group. Every variable the flow set is kept — nothing is dropped.
4. One column per participant-attribute key — the distinct SetParticipantData keys found across the collection (system junk keys already filtered, §4), alphabetical.

Ids are resolved to names in the name columns; multiple values within one conversation join with commas (differing attribute values join with " | "). Guards: 1,000,000 rows, 16,000 dynamic columns, 250 MB source file (beyond that, use the JSON download). The full nested records are always in the JSON.

4Domain concepts

The conversation detail record

The unit of collection is the Genesys analytics conversation detail record: the conversation (conversationId, conversationStart/End, originatingDirection, divisionIds) → its participants (purpose: customer / external / ivr / acd / agent…, userId for agents) → each participant’s sessions (media type, ANI/DNIS, flow reference, media endpoints) → each session’s segments (queue, wrap-up code, requested routing users/skills) and metrics. It is the complete routing/handling history of an interaction — everything except the two enrichments below, which the app adds from other Genesys APIs.

Participant attributes (SetParticipantData)

• Analytics job records do include participant attributes, but Genesys truncates each key and value to 1,024 characters. The app does not use those copies: it takes attributes from the live conversation object, fetching GET /api/v2/conversations/{id} once per kept conversation (the slow “harvesting” phase).
• Per-participant attribute maps are kept on each participant and merged into one conversation-level map (participantAttributes); when participants hold different values for the same key they join with " | ".
• Junk-key filter — Genesys auto-writes internal per-call keys whose names embed GUIDs (screen-connector / routing variables). Keys starting scv_, any key embedding a GUID, keys containing :call.inbound/:call.outbound, and empty values are dropped — otherwise each would become a one-row Excel column. Only human-named SetParticipantData keys survive.
• Conversations older than the live conversations-API retention return 404 — recorded as attributesResolved: false (the analytics fields are still complete; only the custom attributes are missing).

IVR flow execution data

The optional enrichment reads Architect Historical Flow Execution Data: per conversation the app queries its flow instances, batches instance ids into download jobs, fetches the presigned execution documents (no Genesys token needed, so this heaviest stage is not rate-limited), and extracts:

• Collected variables — every author-declared variable (Flow.* / Task.* / Secure.* / State.*, excluding Flow.Version) that holds a real value. Values stringify sensibly: {id,name} objects become the name, Genesys placeholders become (value too large) / (redacted), other objects clip at 400 characters.
• Business vs lookup classification — structural, by flow action type, never by variable name: variables written by caller-input or author-assignment steps are “business”; variables produced by lookup-type actions (actionCallData, actionDataTableLookup, actionFind*/Get*/Search*/Evaluate*/Lookup*) are lookup outputs. This only orders Excel columns — nothing is dropped, so the extraction adapts to any org’s flows.
• DTMF inputs — Collect Input and Menu steps are grouped per action/menu id; each appearance is one attempt, recording the digits entered and whether it failed (no entry, or the step took its __FAILURE__ path). The result per input: final value, attempt count, failure count and the full ordered trail (∅ = no entry).

Windows, intervals & filters

• UTC, inclusive — the interval runs from dateA timeA:00.000Z to dateB timeB:59.999Z, so the end minute is fully included. Times default to 00:00 / 23:59.
• Windowing — the range splits into windows of at most 7 days; each window is one asynchronous analytics details job. Because the job API streams results by cursor there is no offset-paging cap — the whole range comes back, subject only to this app’s 250,000-record safety cap. Conversations are de-duplicated across window boundaries.
• Division filtering — a Genesys-side segmentFilters predicate (divisionId, OR across selections) is tried first; if the org’s job API rejects that dimension (400) the app falls back to an unfiltered job. A record-level filter on divisionIds always runs regardless, so results are correct either way — the fallback just scans more (visible in the Scanned tile).

5Genesys endpoints & permissions

OAuth client scopes

Missing optional scopes degrade gracefully: no divisions panel, ids instead of names, attributesResolved: false, or flow data disabled with the reason recorded — the collection itself still completes.

6Storage, privacy & security

• Collections — each run is kept as a complete JSON collection plus a small summary, so finished collections stay downloadable after a service restart; only the most recent collections are kept.
• Ownership — collections and jobs belong to the OAuth client that created them, not to a browser session: a re-login with the same client still sees and downloads its collections; any other client cannot see them.
• Enrichment cache — each conversation’s participant attributes and flow extraction (a finished conversation’s enrichment never changes) are cached separately per OAuth client. Successes and definitive misses (attributes no longer available, genuinely flow-less conversations) are cached; transient failures never are, so re-runs retry them. Cached flow data also outlives Genesys’ ~10-day flow-execution retention.
• Purge semantics — Delete data deletes only your collections. It does not touch other clients’ collections, partial files from interrupted runs, or the enrichment cache — so the overall counter may not reach zero after a purge. Full removal is available on request from QVCCS.
• Sessions — credentials are held on the server and never sent to the browser; the client secret is kept only for token refreshes and is never written to storage. Sessions end after a period of inactivity, and signing in again with the same client replaces your older session.

7Technology

• Web application — a server-side collection engine with live progress reporting, an Excel workbook that streams straight to your download, and collection files written incrementally so memory stays flat at any collection size.
• Browser interface — a single page: form, live progress, results, downloads and purge, plus a separate sign-in page.
• Engine — collections run as detached background jobs; finished collections are available again after a restart.

Per-window pipeline

1. Probe — best-effort totalHits for the determinate progress bar.
2. Submit the async details job (with the division segment filter when selected, falling back if Genesys rejects it).
3. Poll until FULFILLED (up to ≈ 15 min per window; FAILED/CANCELLED/EXPIRED abort with the Genesys message).
4. Phase A — scan: page through the results, de-duplicate, division-filter, count against the 250,000-record cap.
5. Phase B — harvest: per kept conversation, fetch attributes (cache-aware) and queue flow-instance queries when the IVR option is on.
6. Flow data: batch instance ids into download jobs (shrinking batches automatically so one bad instance is isolated, not fatal), download the presigned documents, extract variables + DTMF trails, then cache per conversation.
7. Fold & write: statistics fold incrementally and each record is appended to the collection — memory stays flat at any size.

After the last window, collected ids resolve to names, the summary is written into the collection and the job completes.

Rate pacing & resilience

• Adaptive pacing — every Genesys call in a session is paced at about 4.5 requests/s, under Genesys’ standard limit; the pace slows on each 429 and eases back up after sustained success. Pace changes appear in the run log.
• Proactive header pacing — Genesys’ inin-ratelimit-allowed/count/reset headers are honoured: when little of a bucket remains, the remaining allowance is spread over the reset window so the run glides under the cap instead of sawtoothing into 429s.
• Retries — 429/503/504 are retried honouring Retry-After; network errors are retried with backoff; a 401 triggers one token refresh + retry, and tokens are refreshed shortly before expiry — long runs never die on token expiry.

Fixed limits

8Troubleshooting

“Provide start and end dates as YYYY-MM-DD.” / “…times as HH:MM (24-hour, UTC).” / “Start (date + time) must be before end…”

Interval validation. Fix the fields — times are UTC and the end time defaults to 23:59.

“Unknown region.” at sign-in

The submitted region isn’t recognised. Pick from the dropdown (reload the login page if it looks empty).

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 per-region). The Genesys error_description is shown verbatim on the login page.

“The service is busy – try again shortly.”

The service is handling as many sign-ins as it can. Same-client re-logins never hit this — your older session is replaced. Try again shortly.

Stuck on “Genesys is preparing the data…”

Big windows genuinely take minutes on Genesys’ side; the app polls up to ~15 min per window. If a window exceeds the ceiling the run errors with “Window N did not finish within 15 minutes” — narrow the range.

“Genesys job FAILED / CANCELLED / EXPIRED: …”

Genesys aborted the details job — usually transient, or the window falls outside the org’s analytics retention. Re-run; if one specific window keeps failing, check its dates against retention.

Badge “truncated” + log “Hit the 250,000-record safety cap”

The range matched more conversations than the per-collection cap. Split the range into multiple collections — the enrichment cache makes the overlap cheap.

Log: “⚠ Analytics job rejected the server-side division filter…”

The org’s job API wouldn’t accept the divisionId segment filter. Nothing to do — the app falls back to filtering the retrieved records locally; results are identical, the job just scans more (watch the Scanned tile).

“Attributes resolved: no” on many rows

Conversations older than the live conversations-API retention are no longer available (a definitive miss — cached so re-runs skip it), or the client lacks conversations:readonly. Old data: expected, the analytics fields are still complete. Missing on recent data: add the scope, sign out/in.

“⚠ Flow execution data needs the architect:readonly scope — skipping IVR flow variables for this run.”

The flow-instances query returned 403. Grant architect:readonly + Architect > Flow Instance > Search / View, sign out/in, re-run. The rest of the collection completed normally.

Flow variables enabled but few or none extracted

“Capture execution data” wasn’t enabled on the flows when the calls ran, or the calls are older than Genesys’ ~10-day flow-execution retention. Flow data is only ever shown from real execution traces — never reconstructed. Enable capture for future calls; overlapping re-runs reuse cached flow data beyond the 10-day window. QVCCS support can probe a single conversation for you.

Log: “⚠ Flow-data job error HTTP 422…”

Genesys’ flow-data jobs endpoint rejects over-large or partly-invalid instance-id sets. Handled automatically — batches shrink down to single ids so one bad instance is isolated, not fatal. A small persistent count just means a few instances weren’t downloadable.

Flow-query failures in the summary

Some per-conversation flow-instance queries errored (usually rate-limiting). Re-run the same range — successes are cached, so only the failures are retried.

Log: “⚠ Rate limit hit — slowing to … req/s” / “◷ Near rate limit — pacing…”

Informational. The pacer backs off on 429s or rate-limit headers and later eases back up (“✓ Sustained success — easing pace”). Long runs simply take longer.

Download says “Collection file has been pruned.”

The file was rotated out by the keep-newest-40 policy or purged. Re-run the collection — overlapping enrichment comes from cache.

Excel download says the collection is too large for Excel

The source JSON exceeds 250 MB. Use the JSON download, or split the range.

“One of your collections is in progress — cancel or wait…” when purging

Purge is blocked while one of your own jobs is running. Cancel it or let it finish, then purge.

“Delete data” ran but the counter isn’t zero

Expected: the counter includes every collection kept by the service, while purge deletes only your own — other clients’ collections and partial files from interrupted runs remain. The enrichment cache is also deliberately left intact.

“Connection interrupted — reconnecting…” on the progress page

The live connection dropped (a network hiccup, laptop sleep). Nothing to do — it reconnects automatically and the progress is replayed; the collection was never at risk.

Suddenly redirected to the login page

Your session ended: after a period of inactivity, because the service was restarted, or because your client signed in again elsewhere. Sign in again — a collection that finished is owned by your OAuth client and is still downloadable; a run in flight during a restart is lost.

Division list says it is unavailable

The client lacks authorization:readonly. Add the scope for division scoping and names; collections still work unfiltered without it.

Are dates local time?

No — all inputs and all exported timestamps are UTC.