User Guide

Everything you need to know about ClarityIQ

1.Overview

ClarityCX is a CX intelligence platform that analyses customer conversations across all channels — phone, chat, email, bot, and social — using four specialised AI agents and a unified 12-category taxonomy. Every conversation is transcribed, scored, and categorised so you can spot cost recovery opportunities, coach agents, and catch emerging issues before they escalate.

  • •Four AI agents: Coaching, Opportunity, Efficiency, and Sentinel — each focused on a different analytical lens
  • •Unified 12-category taxonomy (Billing & Payments, Delivery & Fulfilment, Product Quality, etc.) applied consistently across every channel
  • •Rand-impact quantification for every insight and alert, so you can prioritise by financial return
  • •Real-time anomaly detection that flags sentiment spikes, topic surges, CSAT drops, and compliance failures

2.How ClarityCX Works: Insight → Action → Outcome

Every part of ClarityCX serves one of three stages: it surfaces what is actually happening in your conversations (Insight), tells you exactly what to do about it (Action), and proves whether the outcome moved (Outcome). The detailed sections below explain each feature individually — this is the story they all fit into.

Insight

See what's actually happening

Every conversation is transcribed, scored for sentiment, CSAT, quality, and compliance, and categorised — so patterns, anomalies, and cost leakage surface themselves instead of hiding in call recordings.

DashboardConversationsEarly WarningProcess & Cost Insights
Action

Know exactly what to do

Each insight arrives with a recommended action and its rand impact, and every root cause is tagged agent- or company-controlled — so you know whether to coach, fix a process, or escalate.

Agent PerformanceCoachingProcess & Cost InsightsEarly Warning
Outcome

Prove the impact

Action tracking shows whether last week's flagged insights were resolved or went OVERDUE, coaching plans measure sentiment improvement across the cycle, and reports quantify the rand impact of what changed.

ReportsQuality ScorecardsCoaching progress
  • •Insight — every conversation is transcribed, scored, and categorised; the Dashboard, Conversation detail views, Early Warning alerts, and Process & Cost Insights surface what is actually happening across all channels
  • •Action — each insight comes with a recommended next step and rand impact: coaching priorities on Agent Performance, structured coaching plans on the Coaching page, recommended actions on Process & Cost Insights, and severity-ranked alert responses in Early Warning
  • •Outcome — the Reports page tracks whether flagged insights moved from 'identified' through 'in progress' to 'resolved' (flagging stale ones OVERDUE), coaching plans measure sentiment improvement across the coaching cycle, and Quality Scorecards show team averages over time
  • •The stages repeat as a weekly loop — this week's report flags what to fix, and next week's action tracking shows whether it moved

3.Dashboard

The Dashboard is your command centre. It aggregates every analysed conversation into a single view with KPI tiles, trend charts, contact-reason breakdowns, active alerts, and top recovery opportunities — all updating in real time as new conversations are processed.

  • •KPI tiles show total conversations, average CSAT, negative sentiment rate, and total rand impact at a glance
  • •Sentiment trend chart tracks positive, neutral, and negative sentiment over time
  • •Contact reason distribution breaks down conversations by the 12-category taxonomy
  • •Active alerts and top recovery opportunities appear in side panels for immediate action

4.Client Segmentation (BPO)

If your contact centre serves multiple end-clients (a BPO model), you can label conversations, agents, data sources, and alerts by client so dashboards and reports can be scoped to one client at a time. Client segmentation is optional — the client tools only appear once you have created at least one client, and every view continues to show ALL of your data until you choose a client filter.

  • •Create and manage clients in Settings → Clients — give each end-client a name, an optional colour for chart and filter consistency, and internal notes; inactive clients are hidden from filters but keep their historical data
  • •The client selector appears on the Dashboard and Agent Performance pages once at least one client exists — choose a client to scope every KPI, chart, and coaching view to that client's conversations
  • •Reports can be exported client-scoped — apply the client filter before exporting so the PDF or CSV covers only that client's data
  • •Views show all data until a client filter is chosen — nothing is hidden by default
  • •Data sources can carry a default client, so every conversation ingested from that source is labelled automatically at ingestion

5.Conversations

The Conversations page lists every ingested conversation with its channel, direction, sentiment, status, and key scores. Click any conversation to open the detail view, which shows the full transcript with per-segment sentiment, quality and compliance scores, AI summary, coaching notes, root cause attribution, and topics.

  • •Each conversation shows predicted CSAT, handle time, quality score, and compliance score
  • •Failure demand and repeat contact flags highlight conversations that indicate process problems
  • •Click 'Run Analysis' on any pending conversation to trigger transcription and AI analysis, or let the automatic queue processor handle it
  • •The detail view includes a Handle Time Analysis card that compares the conversation's handle time against the channel-specific AHT target, with an AI explanation of the variance and contributing factors tagged as agent-controlled or company-controlled
  • •The queue status card shows a live progress bar with pending, processing, complete, and error counts
  • •When analysis is running, a progress bar shows the current stage: transcribing → analyzing → complete
  • •Transcript view colour-codes each speaker segment by sentiment for quick scanning

6.Quality Scorecards

Quality Scorecards aggregate completed conversations by agent, producing a ranked leaderboard with average CSAT, quality, compliance, and handle time. Use this to identify top performers, spot coaching opportunities, and track team-wide averages over time.

  • •Agents are ranked by average quality score, with colour-coded indicators for high and low performers
  • •Team-wide KPIs show average CSAT, quality, compliance, and AHT across all agents
  • •Each agent row shows their total conversation count and per-metric averages
  • •Use scorecards to target coaching sessions and measure improvement

7.Process & Cost Insights

Process & Cost Insights surfaces actionable opportunities to recover revenue and improve efficiency. Insights are categorised as cost process (revenue leakage), automation (self-service potential), or conversation quality (agent improvement areas), each with an estimated annual rand impact.

  • •Each insight includes a recommended action and an estimated annual rand impact
  • •Filter by category to focus on cost recovery, automation, or quality improvements
  • •Track insight status from 'identified' through 'in progress' to 'resolved'
  • •The aggregate recovery dashboard shows total potential savings across all insights

8.Early Warning

The Early Warning system detects anomalies in real time — sentiment spikes, topic surges, CSAT drops, SLA breaches, volume anomalies, and compliance failures. Each alert includes severity, rand impact, and a recommended response so you can act before issues escalate.

  • •Alerts are categorised by type and severity (critical, warning, info)
  • •Acknowledge active alerts to track that they've been seen and are being addressed
  • •Filter by status: active, acknowledged, resolved, or all
  • •Total rand impact of active alerts is shown in the summary cards

9.Real-Time Assist

Real-Time Assist sends supervisors live-call alerts while the conversation is still happening. Your telephony platform (Amazon Connect Contact Lens or Genesys Cloud) streams live events to ClarityCX; your alert rules evaluate each event and, when a rule fires, the alert reaches your supervisors in seconds — while the customer is still on the line.

  • •Available as an add-on on Growth and Enterprise plans — configure it in Settings → Real-Time Assist
  • •Rules are off by default — nothing fires until you create and enable a rule
  • •Sentiment floor — fire when live sentiment drops to or below a score you set (e.g. -0.5)
  • •Consecutive negative — fire after a set number of consecutive negative events on a single live contact
  • •Keyword / category rules — fire when the live contact matches a category your telephony platform tags (e.g. retention-risk)
  • •Webhook setup — your telephony admin points Amazon Connect (EventBridge) or Genesys Cloud notifications at the ClarityCX webhook URL shown on the Real-Time Assist settings card, signing every event with the shared HMAC secret (REALTIME_WEBHOOK_SECRET)
  • •Alert fatigue controls — each rule has a cooldown (no repeat alert for the same rule + agent within the window, default 10 minutes) and a daily alert cap per rule + agent (default 20)
  • •When a rule fires, the alert appears in Early Warning with a [Real-Time] prefix and severity badge, and an email is sent to the rule's notify address if one is set
  • •Optional BPO scoping — a rule can be scoped to a single end-client so it only fires for that client's live contacts

10.Team Leader Live Alerting

When a Real-Time Assist alert fires, team leaders see it immediately inside the app — no need to watch the Early Warning page or wait for an email. Three surfaces keep live alerts in front of the people who can act while the call is still in progress.

  • •Alert bell — the Live Alerts bell in the navigation shows a count of unacknowledged live alerts for your organisation; open it to see each alert's agent, severity, and message, acknowledge it, or jump straight to the filtered Early Warning view
  • •Live toasts — while the app is open, a new alert pops up as a toast notification in the bottom-right corner with View and Acknowledge actions; each alert is shown once per session
  • •Critical-alert chime — critical-severity alerts play a short chime; use the speaker icon next to the bell to mute or unmute it (your choice is remembered on this device)
  • •Action queue — the 'Real-Time Alerts — needs action' panel at the top of the Early Warning page lists all unacknowledged live alerts, oldest first, so a team leader can work through them while the calls are still live; acknowledging an alert also acknowledges its linked Early Warning record
  • •Visible to team leaders and admins — the bell, toasts, and queue appear for owners, super users, admins, and executives; plain agent roles don't see live alerts

11.Reports

The Reports page has two tabs. The Operations Intelligence Report is an auto-generated weekly ops review that turns your conversation analysis into an actionable briefing. The Custom Report Builder lets you build your own report by choosing dimensions, metrics, and filters, then export it as a branded PDF or CSV.

  • •Operations Intelligence Report — an auto-generated weekly briefing with seven sections: trend metrics (week-over-week deltas), topic distribution, root cause breakdown, agent leaderboard, agent spotlight narratives, dollar impact, and action tracking
  • •Topic distribution — a clickable horizontal bar chart showing the % of conversations by primary topic; click any bar to drill into the individual conversations driving it
  • •Root cause breakdown — a pie/donut showing the agent vs company vs mixed attribution split, plus a per-topic stacked view, so you can see whether to coach agents or fix processes; each segment drills into the conversations behind it
  • •Agent leaderboard — a table ranked by quality score with colour-coded indicators (green ≥85, amber 70–84, red <70), showing CSAT, compliance, sentiment, top topic, and derived strengths/development areas; click a row to drill into that agent's conversations
  • •Agent spotlight — auto-generated narratives for your best performer, most-improved agent (when a previous period exists), and the agent who needs attention, compiled from coaching notes and root cause drivers — not hardcoded
  • •Trend metrics — every key metric shows a delta vs the previous reporting period (green = improvement, red = deterioration, grey = flat). If no previous-period data exists, it says so rather than showing fake deltas
  • •Dollar impact — a transparent, defensible cost model: (failure_demand × avg_handle_cost) + (repeat_contacts × avg_handle_cost × 2) + (low_quality_conversations × churn_risk_value). avg_handle_cost = AHT × cost_per_minute ÷ 60. The churn-risk value is adjustable (default R500) so you can model different assumptions. The full formula breakdown is shown so you can defend the number to a client
  • •Action tracking — the feedback loop. Last week's briefing flagged insights to fix; this week's report shows whether they moved from 'identified' to 'actioned' or 'resolved'. Insights still sitting at 'identified' are flagged OVERDUE with a red badge. Use the status dropdown on each Process Insight to mark it Identified → Actioned (In Progress) → Resolved
  • •Branded PDF export — the Operations Intelligence Report exports as a ClarityCX-branded PDF (logo + 'A product of SONKAY' header, tenant name and date range footer, 'Confidential — prepared by ClarityCX')
  • •Custom Report Builder — choose a date range (this week, this month, last 30 days, last quarter, custom), group by up to two dimensions (Topic, Agent, Sentiment, Root Cause, Channel, Direction, Status), select metrics (Quality, CSAT, Compliance, AHT, Sentiment, Failure Demand %, Repeat Contact %, Dollar Impact, Conversation Count), and apply optional filters (by topic, agent, sentiment, root cause, channel, quality range)
  • •Custom report output — render on-screen as a dashboard (bars, donut, stacked bars, or tables depending on the grouping), export as a branded PDF, or download raw data as CSV. All charts and tables drill down to the individual conversations behind each group
  • •Save & load templates — save a report configuration (dimensions, metrics, filters, date-range type) with a custom name and re-run it with one click from the 'Load template' dropdown. Templates are private to your user account
  • •Tenant selector (platform owners) — platform admins and owners can switch between tenants from the header to view any tenant's report; tenant users are automatically scoped to their own tenant

12.AI Agents

ClarityCX includes four conversational AI agents you can chat with directly. Each agent specialises in a different analytical domain and can query your conversation data to answer plain-English questions, generate insights, and recommend actions — effectively giving you an on-demand data analyst for each area of your operation.

  • •Insights Agent — answers plain-English questions about root causes, topic trends, and rand impact across all channels. Instead of manually filtering dashboards, you can ask 'What are the top 3 drivers of negative sentiment this week and what is their financial impact?' and get a specific, structured answer with numbers, percentages, and rand amounts
  • •Quality Agent — asks about agent performance, coaching needs, and quality trends. Use it to identify which agents need coaching, what specific behaviours are driving low scores, and which quality criteria are underperforming
  • •Automation Agent — identifies repetitive tasks and conversation types suitable for self-service or automation, helping you reduce failure demand and deflect avoidable contacts
  • •Early Warning Agent — discusses emerging risks, active anomalies, and proactive responses. Ask it to summarise what needs urgent attention and what the recommended response is for each alert
  • •Speed to insight — agents bypass dashboard filtering and return summarised, strategic answers in seconds, shifting your role from hunting for data to interpreting actionable outcomes
  • •Executive-ready output — all agents respond in professional markdown with clear headers, bolded metrics, and specific numbers, making it easy to copy findings directly into briefings, stakeholder reports, or operational action plans
  • •Cross-channel visibility — agents access data across all integrated channels (phone, chat, email, bot, social), giving you a unified view without needing to check each channel separately
  • •Credit usage — each message sent to an AI agent uses integration credits for the AI response, so monitor usage during heavy analysis periods

13.Custom Agents

Enterprise customers can build their own AI agents tailored to their business from the Custom Agents page. You define the agent's persona and focus area by writing instructions — the agent automatically inherits access to your full conversation analysis data (sentiment, topics, process insights, and rand impact), so no tool configuration is needed. Custom agents are a configurable extension of the built-in agent suite, created from the front end rather than in code.

  • •Enterprise-only — custom agents are available exclusively on the Enterprise plan; Starter and Growth customers see an upgrade prompt
  • •Build from the front end — give your agent a name, a short description, and detailed instructions describing its persona, focus area, and how it should answer (no code or tool configuration required)
  • •Automatic data access — every custom agent inherits your full CX dataset (sentiment breakdown, top topics, channel mix, process insights, and rand impact) so it can answer questions grounded in your real data
  • •Credit cost — creating a custom agent costs 100 credits, and each query to that agent costs 2 credits; both costs are shown in the builder and the chat panel before you act
  • •Your credit balance is shown in the sidebar of the Custom Agents page and updates after each creation or query
  • •Manage your agents — select an agent to chat with it, or delete it from the list; the query count on each card shows how many times an agent has been used
  • •Use cases — build an escalation risk predictor, a churn-cost analyst, a compliance-gap finder, or any specialist tailored to your operations; the agent answers in clear markdown with specific numbers and rand amounts

14.Text Ingest

Text Ingest lets you manually add chat, email, or bot conversations for analysis without needing an audio file. Paste the conversation text, specify the channel and direction, and the system will analyse it using the same AI pipeline as audio conversations.

  • •Supports chat, email, bot, and social channels — no audio required
  • •Each ingested conversation goes through the full AI analysis pipeline
  • •Useful for analysing text-based channels that don't have call recordings
  • •Ingested conversations appear in the Conversations list alongside audio ones

15.Integrations

The Integrations page connects ClarityCX to your telephony and CRM platforms. Supported sources include Genesys, Avaya, Cisco, Twilio, Amazon Connect, RingCentral, Talkdesk, Salesforce, Zendesk, and HubSpot, plus manual upload for one-off imports.

  • •Each data source shows connection status, sync frequency, and conversations ingested
  • •Configure sync frequency as realtime, hourly, or daily depending on your needs
  • •Error messages surface connection issues so you can troubleshoot quickly
  • •Manual upload is always available as a fallback for ad-hoc imports

16.Audio Upload

Audio Upload lets you upload call recordings for automatic transcription and AI analysis. Upload an audio file, and the system transcribes it, runs the full analysis pipeline, and makes the conversation available in the Conversations list with all scores and insights.

  • •Supports common audio formats — the system transcribes automatically after upload
  • •Each upload creates a conversation record and triggers the analysis pipeline
  • •Uploaded conversations are analysed automatically by the queue processor — no manual action needed
  • •Track processing status from 'pending' through 'transcribing' and 'analyzing' to 'complete'
  • •Once complete, the conversation appears in the Conversations list with full insights

17.Automated Analysis & Queue Processing

ClarityCX automatically processes pending conversations through a batch queue system, so you don't need to manually trigger analysis on every conversation. Whether conversations arrive via audio upload, text ingest, or telephony integration, they are picked up and analysed automatically with controlled concurrency to ensure stability under high load.

  • •The queue processor runs every 5 minutes. By default it picks up 3 pending conversations per run and processes 2 at a time, but both the batch size (1–6) and concurrency (1–5) are configurable per tenant in Settings under Processing Throughput
  • •New conversations from uploads, text ingest, or integrations are analysed automatically — no manual action required
  • •Failed analyses are automatically retried up to 2 times before being left in 'error' status for manual review
  • •The queue status card on the Conversations page shows a live progress bar with pending, processing, complete, and error counts, and auto-refreshes every 10 seconds while the queue is active
  • •Manual 'Run Analysis' is still available on individual conversations for immediate processing when needed
  • •Default throughput is approximately 864 conversations per day (3 per run × 12 runs/hour × 24 hours). At the maximum batch size of 6, throughput reaches up to 1,728 conversations per day — capped to stay under 2,000/day and avoid API rate limits

18.Performance Targets & Throughput

Admins can set benchmark targets for key contact centre metrics and configure processing throughput directly in Settings. These targets define your performance goals and serve as the baseline for comparing actual results across the platform, while throughput settings control how fast conversations are processed.

  • •CSAT target — desired customer satisfaction score on a 1-5 scale (default 4.5)
  • •SLA adherence — target percentage of conversations meeting service level (default 80%)
  • •Quality score — target agent quality score out of 100 (default 85)
  • •Compliance score — target compliance score out of 100 (default 95)
  • •Average handle time — per-channel AHT targets (in seconds) set separately for phone (default 300), chat (600), email (1,800), bot (60), and social (900); the general AHT target serves as a fallback for any channel not explicitly customised
  • •Negative sentiment — maximum acceptable negative sentiment rate (default 10%)
  • •Batch size — number of conversations picked up per queue run, configurable 1–6 (default 3)
  • •Concurrency — number of analyses processed simultaneously within a batch, configurable 1–5 (default 2)
  • •Daily throughput is capped at 1,728 conversations (6 × 288 runs/day) to stay under 2,000 and avoid API rate limits
  • •Targets and throughput settings are saved per tenant and can be updated at any time from the Settings page

19.Billing & Credits

ClarityCX operates on a prepaid credit model. Each plan includes monthly credits (1 credit = 1 analysis). When credits run out, analyses pause until you top up or your credits refresh next cycle. No overage charges — you're always in control of your spend. Top-up packs are available in 4 sizes and are valid for 60 days from purchase.

  • •Three plans: Starter (R6,500/mo, 9,000 credits / 9,000 conversations), Growth (R14,000/mo, 36,000 credits / 36,000 conversations), Enterprise (R42,000/mo, 135,000 credits / 135,000 conversations)
  • •Prepaid only — 1 credit per analysis, analyses pause at zero, no overage charges
  • •Credits refresh at the start of each billing cycle
  • •Credit top-up packs — 5,000 credits (R3,750), 10,000 credits (R7,000), 40,000 credits (R26,000), 100,000 credits (R55,000); purchasable via Payfast at any time. Top-up credits are valid for 60 days from purchase (the month of purchase plus one full month of rollover) — unused top-ups lapse after that, with an expiry entry in the Credit History explaining any balance drop. They are priced above the subscription per-credit rate to incentivise subscribing
  • •Credit balance, credits used this cycle, credits remaining, next refresh date, and full transaction history are visible on the Billing page
  • •Automated email warnings are sent to your primary contact at 80% and 95% credit usage, and when credits are exhausted

20.How Credits Are Used

ClarityCX uses two types of credits: billing credits (included in your plan or purchased as top-ups) and integration credits (the platform-level AI compute consumed by each operation). Understanding what consumes credits helps you manage usage and avoid running out mid-cycle.

  • •Conversation analysis — each analysed conversation uses 1 billing credit plus integration credits for transcription (if audio) and the AI analysis call
  • •Process insight generation — the 'Generate Insights' button uses integration credits to run an AI analysis across your conversations
  • •AI agent conversations — each message sent to the Coaching, Opportunity, Efficiency, or Sentinel agents uses integration credits for the AI response
  • •Custom agents (Enterprise) — creating a custom agent uses 100 billing credits, and each query to a custom agent uses 2 billing credits plus integration credits for the AI response
  • •Weekly digest & anomaly detection — scheduled automations use integration credits for AI processing and email delivery
  • •Billing credits only apply to conversation analysis — top up via the Billing page if your balance reaches zero

21.How CSAT Is Calculated

ClarityCX measures customer satisfaction (CSAT) on a 1-5 scale. There are two sources of CSAT data — AI-predicted and actual survey — and the platform uses the best available source for each conversation. Understanding how CSAT is obtained and scored helps you interpret the metrics correctly.

  • •Predicted CSAT — when no survey data is available, the AI analyses the conversation transcript and predicts a CSAT score (1-5) based on sentiment, agent performance, issue resolution, and customer language cues. This is an estimate, not a customer-rated score
  • •Actual CSAT (Survey) — when you provide post-interaction survey data via the Survey Import page, the real customer-rated score replaces the AI prediction for that conversation. The customer's verbatim comment is also stored and displayed alongside the score
  • •Source priority — if a conversation has an imported survey score, the actual CSAT is used everywhere CSAT appears (Dashboard, Reports, Quality Scorecards, Conversation Detail). Conversations without survey data continue to use the AI-predicted score
  • •CSAT methodology — in Settings you can define which survey ratings count as 'meeting' your CSAT target: Top-Box (only 5-star ratings count), Top-2-Box (4-star and 5-star ratings count), or Average Score (the mean of all survey scores is compared to your target)
  • •CSAT target adherence — the percentage of conversations whose survey score meets your chosen methodology threshold is compared against your CSAT target adherence percentage (e.g., 80% of conversations scoring 4 or 5)
  • •Importing survey data — use the Survey Import page to upload a CSV (columns: external_id, csat_score, verbatim) or enter individual survey responses manually. Survey data is matched to conversations by their external ID from your telephony platform

22.How Sentiment Is Rated

Sentiment is an independent AI judgment of the customer's emotional tone, not a formula derived from CSAT or QA. Understanding what sentiment measures — and what it deliberately does not measure — is essential for interpreting it correctly next to your other scores.

  • •What sentiment measures — the customer's emotional tone during the conversation: were they frustrated, happy, or calm and measured? It reflects how the customer felt, not whether their issue was resolved
  • •How it's scored — the AI reads the entire transcript and produces two values: an overall label (positive, neutral, or negative) and a numeric sentiment score from -1 (very negative) to +1 (very positive), where 0 is neutral. Each transcript segment also gets its own sentiment label and score, so you can see where tone shifted mid-conversation
  • •Per-segment colour-coding — the transcript view colours each speaker segment green (positive), grey (neutral), or red (negative), letting you scan a long call and spot the moments where sentiment turned
  • •Independent of CSAT and QA — sentiment is not calculated from CSAT or quality score. All three are produced separately by the AI and measure different things: sentiment = how the customer felt, CSAT = how satisfied the AI thinks the customer is with the outcome, quality = how well the agent followed the rubric
  • •Neutral sentiment with low CSAT and low QA is valid and common — a customer can stay calm and measured (neutral tone → neutral sentiment) while the agent fails to resolve the issue (low CSAT) and misses rubric steps (low QA). The emotional state was neutral even though the outcome was poor
  • •Why the separation matters — sentiment alone would never reveal a calm-but-unresolved call. Splitting the three scores is exactly how ClarityCX surfaces failure-demand and repeat-contact patterns that hide behind a neutral emotional tone
  • •No hard-coded thresholds — the AI's sentiment judgment is stored directly; there is no fixed score-to-label formula in the platform. The negative sentiment target in Settings (default 10%) sets your acceptable rate of negative-sentiment conversations, not how the label itself is assigned

23.First Contact Resolution (FCR)

ClarityCX predicts First Contact Resolution (FCR) for every analysed conversation. FCR measures whether a customer's issue was fully resolved on their first contact, without the need for a follow-up interaction. This is one of the most important operational metrics in a contact centre — high FCR rates correlate directly with higher CSAT, lower operating costs, and reduced repeat contact volume.

  • •AI-predicted — the AI analyses the conversation transcript to determine whether the customer's issue was resolved during this interaction, considering resolution cues, agent confidence, and the absence of escalation or follow-up indicators
  • •Confidence score — each FCR prediction includes a confidence score (0-100) indicating how certain the AI is about its assessment. Scores above 80% are high-confidence predictions
  • •FCR is closely related to the 'repeat contact' flag — a conversation flagged as a repeat contact is unlikely to be an FCR, since the customer has been in touch before about the same issue
  • •FCR appears on the Dashboard as a percentage rate, on individual conversation detail pages as a resolved/unresolved indicator, and in Reports alongside other KPIs
  • •Use FCR to identify agents or topics with low resolution rates — these are prime targets for coaching, process improvement, or knowledge base updates

24.Root Cause Attribution

Every analysed conversation includes a root cause attribution that classifies the primary driver of the conversation's outcome as agent-controlled, company-controlled, or mixed. This helps you distinguish between coaching opportunities (things the agent can improve) and systemic issues (things the company needs to fix through policy, process, or product changes).

  • •Agent — the outcome was primarily driven by factors within the agent's control (tone, empathy, product knowledge, procedure adherence, effort, hold/transfer handling). These are coaching opportunities
  • •Company — the outcome was primarily driven by factors outside the agent's control (policy restrictions, product defects, system outages, billing errors, process gaps, staffing, long queue times). These require policy, process, or product changes
  • •Mixed — both agent and company factors contributed roughly equally to the outcome
  • •Each conversation also lists specific root cause drivers — the individual factors that contributed to the outcome, each tagged as agent-controlled or company-controlled with a brief explanation
  • •Use the Agent vs Company breakdown on the Dashboard to see what proportion of your negative outcomes are coaching issues versus systemic issues — this helps you decide where to invest improvement effort
  • •The Root Cause card on the conversation detail page shows the attribution and all drivers, making it easy to understand why a conversation went the way it did

25.AHT Variance Analysis

Every analysed conversation includes an Average Handle Time (AHT) variance analysis. The platform compares the conversation's actual handle time against the target AHT for its specific channel and uses AI to explain why the handle time was longer or shorter than target, categorising the contributing factors as agent-controlled or company-controlled.

  • •Per-channel targets — AHT targets are set per channel (phone, chat, email, bot, social) in Settings, so a 5-minute phone target and a 30-minute email target can coexist without conflict
  • •The variance is calculated as actual handle time minus the channel-specific target — positive means over target, negative means under
  • •The AI explains WHY the handle time deviated from target, considering factors like unnecessary holds, lack of product knowledge, complex policies, system issues, and customer preparation
  • •Each contributing driver is tagged as 'agent' (within the agent's control — coaching opportunity) or 'company' (outside the agent's control — policy/process issue)
  • •The Handle Time Analysis card on the conversation detail page shows the actual handle time, variance, target, explanation, and drivers
  • •If no duration is available from the source, the platform estimates handle time from the transcript length or segment timestamps
  • •Use AHT variance analysis to identify whether handle time issues are coaching opportunities (agent-controlled) or systemic issues (company-controlled)

26.How Costs Are Calculated

ClarityCX estimates the operational cost of each conversation and quantifies the annualised financial impact of process issues and recovery opportunities. Understanding these calculations helps you prioritise actions by financial return.

  • •Estimated conversation cost — each conversation's cost is calculated as (duration in minutes × cost per minute). The cost per minute is configurable in Settings under CSAT & Cost Configuration (default: R2.50/minute). This provides an approximation of the operational cost of handling the interaction
  • •Cost is calculated automatically — the estimated cost is set during AI analysis based on the conversation's duration (or average handle time if available) and your configured cost-per-minute rate
  • •Rand impact on insights — process insights estimate the annualised financial impact of an identified issue by multiplying the estimated cost per affected conversation by the volume of affected conversations over a year. This helps you prioritise by financial return
  • •Rand impact on alerts — early warning alerts quantify the financial risk of detected anomalies (sentiment spikes, compliance failures, etc.) using the same cost-per-conversation basis
  • •Recovery identified — the total recovery figure shown on the Dashboard and Reports is the sum of all rand impacts across active process insights, representing the total annualised savings opportunity if all identified issues were resolved
  • •Cost per minute is adjustable — update your cost-per-minute rate in Settings to reflect your actual staffing, infrastructure, and overhead costs per agent minute. All cost calculations update automatically on subsequent analyses

27.Data Retention (Process-and-Purge)

ClarityCX supports two data retention modes. Full Retention (the default) keeps all raw audio and transcripts indefinitely so you can replay and re-read any conversation. Process-and-Purge deletes the raw audio and transcript for a conversation after a configurable age while keeping every extracted insight — so reporting, dashboards, and briefings stay complete even after the source material is gone. Retention access is gated by the platform owner and must be enabled per tenant before the tenant can configure it.

  • •Full Retention (default) — raw audio_url, transcript, and transcript_segments are kept forever; conversations can be replayed and re-read at any time
  • •Process-and-Purge — once a conversation is older than the configured purge age (in hours), the purge job clears only the three raw-data fields (audio_url, transcript, transcript_segments) and stamps a purged_at timestamp for audit
  • •Insights are always preserved — sentiment, sentiment score, topics, predicted/actual CSAT, AHT and its variance/drivers, compliance score, quality score, FCR, root cause attribution and drivers, estimated cost, and the analysis summary all remain on the conversation record and continue to appear in every report, dashboard, trend chart, and briefing exactly as before
  • •Purge age is configurable in hours — set it to 0 to purge raw data immediately once analysis is complete, or any positive number of hours to retain it for that window; null means not applicable (Full Retention)
  • •The purge job runs automatically on a schedule across all tenants opted into Process-and-Purge, processing up to 500 conversations per run for safety and logging each purged conversation
  • •Retention access is owner-controlled — the Data Retention settings card is hidden by default and only appears for a tenant once the platform admin enables the 'Retention Access' toggle for that tenant on the Client CRM page; tenants cannot enable it themselves
  • •Already-purged conversations are skipped on subsequent runs, and conversations still holding raw data are the only ones touched — making the job idempotent and safe to re-run

28.Improvement Area Taxonomy

Every analysed conversation includes an improvement area classification. When the agent's performance was the primary driver of a negative or mixed outcome, the AI tags the single most impactful improvement area — helping you focus coaching on the right skill rather than a vague 'do better'. When the call was positive, neutral, or the root cause was company-side, the area is set to n/a.

  • •soft_skills — empathy, tone, de-escalation, active listening, and rapport. Example: the agent sounded dismissive when the customer expressed frustration, escalating the emotional temperature instead of calming it
  • •product_knowledge — gave wrong information, didn't know the answer, or couldn't explain a product or policy. Example: the agent told the customer the wrong returns window, causing a follow-up call to correct it
  • •process_knowledge — didn't follow the correct workflow, missed an escalation step, or applied the wrong process. Example: the agent should have escalated to a supervisor after two failed resolution attempts but continued retrying instead
  • •communication — unclear explanations, talking over the customer, using jargon, or poor conversational structure. Example: the agent gave a technically correct answer but in jargon the customer didn't understand, leading to confusion and a repeat contact
  • •system_navigation — struggled with tools or systems, slow system handling, or couldn't find the information needed. Example: the agent spent several minutes clicking through multiple screens to find the customer's order status, stretching the handle time
  • •n/a — used when the call was positive or neutral, OR when the root cause was company-side (policy restriction, product defect, system outage) rather than the agent's performance. Company-side root causes are not coaching opportunities and are never tagged with an improvement area
  • •Only one area per conversation — the AI picks the single most impactful factor, not a list, so coaching priorities stay focused
  • •Each non-n/a classification includes a one-sentence improvement_detail explaining exactly what the agent could improve, grounded in the conversation content

29.How Agent Performance Works

The Agent Performance page turns the per-conversation analysis into a single-agent trend and coaching view. Understanding the data flow helps you trust the charts and know exactly what each visualisation is built from.

  • •Data source — every chart on the Agent Performance page is built from existing Conversation records filtered by the selected agent, the signed-in user's tenant, the chosen date range, and a status of 'complete' (or conversations that have an analysis summary). No data is fabricated or estimated beyond what the analysis pipeline already produced
  • •Sentiment trend — the daily line chart averages the sentiment_score of every completed conversation for that agent on each day in the range. Green segments are days where the daily average was above zero; red segments are days below zero. A shaded neutral band marks the -0.1 to +0.1 zone where sentiment is effectively flat
  • •Call distribution donut — counts each completed conversation by its overall_sentiment label (positive, neutral, negative) and shows the total in the centre. This is a raw count, not a weighted score
  • •Category heatmap — groups completed conversations by primary_topic and computes total calls, average sentiment score, average quality score, and the positive and negative percentage for each topic. The average sentiment cell is colour-coded green (>0.3), yellow (-0.1 to 0.3), or red (< -0.1) for instant scanning
  • •Improvement area breakdown — counts only conversations where improvement_area is not n/a (i.e. the agent's performance was the primary driver of a negative or mixed outcome), grouped by the five improvement areas. The percentage is relative to the total number of negative-sentiment conversations for that agent in the range
  • •Coaching priorities — the auto-generated card cross-references the primary_topic with the improvement_area for every agent-driven negative/mixed call, counts each combination, and ranks the top three by count. Each priority shows the improvement area, the topic, the number of negative calls, and the average sentiment across those calls
  • •Plan gating — Starter shows the sentiment trend and call distribution donut; Growth adds the category heatmap, improvement area breakdown, and coaching priorities; Enterprise adds PDF export of the report and side-by-side agent comparison
  • •Real-time — the data is fetched fresh each time you change the agent, date range, or plan simulation, so the charts always reflect the latest analysed conversations