Designing MOS Score Trending Dashboards with Automated Degradation Alerting

What This Guide Covers

This guide details the architecture for monitoring Mean Opinion Score (MOS) or equivalent Quality Management scores using Genesys Cloud CX Analytics API and native Alerting constructs. You will configure a production-ready dashboard that tracks score degradation over time and triggers automated notifications when quality drops below defined thresholds. The end result is a system that detects quality anomalies before they impact customer experience, utilizing rolling aggregation windows to filter out statistical noise while maintaining low latency for critical alerts.

Prerequisites, Roles & Licensing

To implement this solution, the following prerequisites must be met within your Genesys Cloud CX environment:

• Licensing Tier: You must have a CCaaS subscription that includes Quality Management and Analytics Reporting. Network Quality MOS data requires specific carrier integration or SIP trunking configurations enabled on the platform.
• Granular Permissions: The user account executing these configurations requires the following permission strings in their role assignment:
  • Analytics > Reports > View (to query historical quality data)
  • Alerts > Edit (to create and manage degradation alerts)
  • Quality Management > Manage Surveys (if utilizing QA scores as MOS proxy)
• OAuth Scopes: If automating the dashboard creation via API, the OAuth token must include the scope analytics:read and alerts:write.
• External Dependencies: You must have a defined threshold strategy for degradation. For example, a 10% drop from baseline or an absolute score below 3.5 out of 5.

The Implementation Deep-Dive

1. Data Source Selection and Aggregation Strategy

The first architectural decision involves selecting the correct data source for MOS metrics. In Genesys Cloud CX, there is a distinction between Voice Quality (network-based MOS) and Quality Management (survey-based scores). Most organizations use QA Survey scores as their primary MOS proxy because they reflect customer perception rather than network fidelity.

You must choose between Real-time Streaming Data and Historical Batch Processing. Real-time data is available via the WebSocket API but contains significant latency variance due to SIP signaling delays. For trending dashboards, you must utilize the Analytics Reporting API v2. This endpoint provides aggregated data points that smooth out micro-fluctuations which would otherwise trigger false positive alerts.

The Trap: A common misconfiguration involves querying raw interaction logs without aggregation windows. If you attempt to calculate a MOS score from individual call records in real-time, the denominator (sample size) will be zero during off-hours or low-volume periods, leading to division-by-zero errors and infinite loops in alerting logic.

Architectural Reasoning: You must configure your API query to aggregate data into 15-minute windows. This aligns with standard WFM reporting intervals and ensures that every data point represents a statistically significant sample of interactions. Use the granularity parameter set to FIFTEEN_MINUTES. Do not use hourly granularity, as it masks rapid degradation events that require immediate intervention.

Code Snippet:
When constructing the API payload for the quality dataset, ensure you include the interval and metrics parameters explicitly.

{
  "interval": {
    "granularity": "FIFTEEN_MINUTES",
    "dateRange": {
      "from": "2023-10-01T00:00:00Z",
      "to": "2023-10-01T23:59:59Z"
    }
  },
  "metrics": [
    {
      "metricId": "quality_score",
      "aggregationType": "AVERAGE"
    },
    {
      "metricId": "quality_total_interviews",
      "aggregationType": "SUM"
    }
  ],
  "filters": [
    {
      "dimensionKey": "queue_id",
      "operator": "EQ",
      "values": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ]
    }
  ]
}

2. Configuring the Degradation Thresholds

Once data ingestion is established, you must define the logic for degradation alerting. A flat threshold (e.g., Alert if MOS < 3.0) is insufficient because quality scores naturally fluctuate based on interaction complexity and time of day. You require Dynamic Baseline Comparison.

The implementation requires a comparison between the current window score and a historical baseline (typically the previous week or month). This normalizes the data against seasonal trends, such as higher call volumes during holiday seasons which often correlate with lower quality scores due to increased stress.

The Trap: Setting thresholds without accounting for Minimum Sample Size. An alert triggered by a single interaction with a low score is statistically insignificant and creates “alert fatigue.” If your system alerts on a 2.0 score from one call, but the average remains 4.0, you will desensitize the operations team to real issues.

Architectural Reasoning: You must implement a Hysteresis Logic in your alert configuration. This means the threshold for triggering an alert (e.g., < 3.5) must be different from the threshold for clearing the alert (e.g., > 4.0). This prevents oscillation where an alert triggers, clears, and triggers again within a short timeframe due to boundary fluctuations.

Code Snippet:
When defining the Alert via the API (POST /alerts), include the thresholds configuration with both lowerBound and upperBound logic if your platform supports conditional evaluation. For Genesys Cloud native alerts, you configure this in the UI under Analytics > Alerts, but for programmatic control, use the following JSON structure:

{
  "name": "Quality Degradation Alert - High Priority",
  "type": "METRIC_THRESHOLD",
  "metricName": "quality_score",
  "comparisonOperator": "LESS_THAN",
  "thresholdValue": 3.5,
  "durationInSeconds": 900,
  "notificationChannels": [
    {
      "channelType": "EMAIL",
      "recipients": [
        "ops-team@company.com"
      ]
    },
    {
      "channelType": "WEBHOOK",
      "url": "https://monitoring.company.com/webhooks/quality-alert"
    }
  ],
  "frequency": "ONCE_PER_DEGRADATION",
  "cooldownPeriodSeconds": 3600
}

The durationInSeconds parameter is critical. It requires the condition to hold true for 15 minutes (900 seconds) before firing. This filters out transient network blips that do not represent systemic quality degradation. The cooldownPeriodSeconds ensures that once an alert fires, it does not spam the team with repeated notifications until the system recovers or a significant new change occurs.

3. Dashboard Visualization and Embedding

A trending dashboard requires more than just data; it requires context. Native Genesys Cloud Dashboards are powerful but can be rigid when custom correlation is needed. For a Principal Architect level implementation, you should construct a Custom Analytics View that correlates Quality Scores with Volume Metrics simultaneously.

You must visualize the MOS trend against a Rolling Average. A 15-minute moving average smooths the data curve, making degradation patterns visually apparent. Additionally, overlay the Minimum Sample Size line on the same chart. This allows you to see immediately if a dip in quality is due to a drop in volume (where the score becomes unreliable) or an actual performance issue.

The Trap: Overcrowding the dashboard with too many metrics. Including Network Quality MOS alongside QA Survey MOS can confuse the audience because they measure different things (network fidelity vs customer perception). If both are present, you must clearly label them and distinguish their data sources in the legend. Failure to do so leads to confusion during incident response, where engineers might investigate network latency for a problem that is actually agent training related.

Architectural Reasoning: Use Dual-Axis Charts. Plot the MOS Score on the primary Y-axis (Left) and the Interaction Volume on the secondary Y-axis (Right). This allows you to see if a quality dip coincides with a volume spike. If volume spikes while MOS drops, it indicates capacity issues. If volume stays flat and MOS drops, it indicates agent proficiency or training gaps.

Code Snippet:
To embed this custom view into an external BI tool like Tableau or PowerBI using the Genesys Cloud API, you would construct a request that pulls the specific dataset ID for Quality Management. Ensure you pass the timezone parameter to align the data with your operations team’s local time zones to avoid off-by-one-hour errors in shift reporting.

{
  "datasetId": "quality",
  "viewName": "Quality Degradation Trend - US-East",
  "filters": {
    "timezone": "America/New_York"
  },
  "aggregations": [
    {
      "name": "MOS Trend",
      "function": "AVG",
      "field": "quality_score"
    },
    {
      "name": "Volume Trend",
      "function": "COUNT",
      "field": "interaction_id"
    }
  ]
}

Validation, Edge Cases & Troubleshooting

Edge Case 1: Data Latency and Reporting Delays

The Failure Condition: You configure an alert for a MOS drop, but the notification arrives 30 minutes after the degradation occurred.
The Root Cause: Analytics reporting in Genesys Cloud CX has inherent latency due to batch processing of interaction data. Real-time streaming data is available, but quality scores often require post-call survey completion which can take hours or days depending on customer response time.
The Solution: You must distinguish between Network Quality (near real-time) and Survey Quality (delayed). For the dashboard, configure separate alert rules. Network MOS alerts can trigger within 5 minutes of a call ending. Survey-based MOS alerts should have a cooldownPeriodSeconds of at least 86400 (24 hours) to account for survey response latency. Do not attempt to force real-time notification on survey data; it will result in false positives as early responses are often biased.

Edge Case 2: Sample Size Variance During Low Volume

The Failure Condition: The dashboard displays a MOS score of 1.0 during the night shift, triggering an alert, but the team ignores it because only one call was completed.
The Root Cause: Statistical insignificance. A single interaction can skew the average significantly.
The Solution: Implement a Minimum Threshold Filter in your query logic. Do not display or alert on data points where quality_total_interviews is below a specific count (e.g., 5 interactions per window). In the API payload, add a filter condition: quality_total_interviews >= 5. This ensures that every point on your trend line represents a statistically valid sample size.

Edge Case 3: Time Zone Mismatch in Trending

The Failure Condition: The degradation alert triggers at 04:00 UTC, but the US team expects it to be 21:00 local time, causing confusion about which shift is affected.
The Root Cause: The API returns timestamps in UTC by default, while the UI renders data based on user preferences or server configurations.
The Solution: Explicitly pass the timezone parameter in every API call to ensure consistency between the alert trigger time and the dashboard visualization. Document this requirement for all dashboards that feed into WFM (Workforce Management) reports, as shift definitions are strictly time-zone dependent.

Official References

• Genesys Cloud CX Analytics Reporting API: https://developer.genesys.cloud/developer/api/rest/analytics
  • Detailed documentation on query parameters, metric IDs, and aggregation types for quality data sets.
• Genesys Cloud CX Alerts Configuration: https://help.mypurecloud.com/articles/configure-alerts-in-analytics/
  • Step-by-step instructions for creating threshold-based alerts and configuring notification channels.
• Quality Management Metrics Documentation: https://help.mypurecloud.com/articles/quality-metrics/
  • Definitions of all quality-related metrics available in the Analytics engine, including survey scores and interaction attributes.