Implementing Real-Time Evaluation Score Feeds for Intraday Quality Monitoring Dashboards

How-To-Articles
1

Implementing Real-Time Evaluation Score Feeds for Intraday Quality Monitoring Dashboards

What This Guide Covers

This guide details the architectural and implementation steps required to stream Genesys Cloud CX Quality score data into external dashboards for intraday visibility. You will configure the Quality API data pipeline to expose evaluation metrics, implement OAuth 2.0 client credentials for secure access, and construct the necessary SQL-like queries or REST calls to aggregate scores by agent, queue, or skill in near real-time. The end result is a reliable data feed that updates every 15 minutes, enabling supervisors to intervene on performance trends before the end of the day.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 1, 2, or 3 license with the Quality module enabled.
  • User Permissions:
    • quality > evaluation > view
    • quality > evaluation > export
    • admin > org > view (for org ID retrieval)
    • integration > oauth > view and edit (to create the service account)
  • Technical Dependencies:
    • An external dashboarding tool capable of making HTTP GET requests and rendering JSON (e.g., Power BI, Tableau, Grafana, or a custom React/Node.js application).
    • A service account configured with Client Credentials flow.
    • Access to the Genesys Cloud Developer Center for API documentation.

The Implementation Deep-Dive

1. Architectural Strategy: Why Real-Time Quality Data Is Different

Before writing a single line of code, you must understand the data lifecycle in Genesys Cloud Quality. Unlike interaction data (which streams via Webhooks or the Interaction API), Quality data is eventually consistent and batch-oriented.

When an evaluator submits a score, the system does not immediately push that score to an external database. Instead, the score is stored in the Quality database. The Quality API then exposes this data through two primary mechanisms:

  1. The Evaluation API: Retrieves individual evaluation records.
  2. The Quality Metrics API: Aggregates scores into metrics (averages, counts, pass/fail rates).

The Trap: Attempting to use Webhooks for Quality data.
Genesys Cloud does not provide a webhook trigger for evaluation.created or evaluation.updated that exposes the full score payload in a format suitable for dashboarding. While you can trigger a webhook on evaluation submission, the payload is minimal (metadata only). If you attempt to build a real-time dashboard using a webhook listener, you will find yourself making a secondary API call to fetch the details for every single webhook event. Under high volume, this creates a thundering herd problem against your API rate limits.

The Solution: Use the Quality Metrics API with a polling interval of 15 minutes.
Genesys Cloud updates quality metrics in 15-minute windows. This is the “real-time” threshold for Quality. Polling every 15 minutes aligns with the platform’s data refresh cycle, ensuring you never request data that has not yet been calculated, and you avoid unnecessary API calls.

2. Configuring the Service Account and OAuth

You must isolate this data pipeline from human users. Do not use a supervisor’s login credentials. Create a dedicated Service Account.

  1. Navigate to Admin > Security > OAuth clients.
  2. Click Add client.
  3. Set Name to Quality-Dashboard-Service.
  4. Set Grant types to client_credentials.
  5. Set Scopes to:
    • quality:evaluation:read
    • quality:metric:read
    • interaction:call:view (if correlating with call details later)
  6. Save and record the Client ID and Client Secret.

The Trap: Granting quality:evaluation:write or edit scopes.
Principle of Least Privilege is critical. Your dashboard is read-only. If you grant write permissions, you risk accidental data corruption if your application logic has a bug that sends a PUT request instead of a GET. More importantly, if the service account credentials are leaked, an attacker cannot modify evaluation scores or delete evaluations.

3. Constructing the Data Query: The Quality Metrics API

The core of your dashboard is the /api/v2/quality/metrics endpoint. This endpoint allows you to slice and dice quality data by time, agent, queue, or skill.

Step 3.1: Authentication

First, obtain an access token using the Client Credentials flow.

POST https://{{org_domain}}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 3.2: Defining the Metric Request

You must define which metrics you want to retrieve. The most common metrics for intraday monitoring are:

  • averageScore: The average score of all evaluations.
  • count: The number of evaluations completed.
  • passRate: The percentage of evaluations marked as “Pass”.

The Trap: Retrieving all metrics without filtering.
The Quality Metrics API returns a vast array of possible metrics. If you do not specify the metrics parameter, the response payload will be large, and the processing time on your dashboard side will increase. Always specify the exact metrics you need.

Step 3.3: The API Call

To get intraday data, you must filter by startTime and endTime. For a real-time dashboard, set startTime to the beginning of the current business day and endTime to the current time.

GET https://{{org_domain}}/api/v2/quality/metrics?startTime=2023-10-27T08:00:00Z&endTime=2023-10-27T17:00:00Z&groupBy=agent&metrics=averageScore,count,passRate
Authorization: Bearer {{access_token}}

Parameters Explained:

  • startTime/endTime: ISO 8601 format. Use UTC.
  • groupBy: Determines the granularity. Options include agent, queue, skill, evaluationForm, or evaluator. For agent-level monitoring, use agent.
  • metrics: Comma-separated list of metric keys.

Step 3.4: Handling the Response

The response is an array of metric objects.

[
  {
    "entityId": "agent-id-123",
    "entityName": "John Doe",
    "metrics": {
      "averageScore": {
        "value": 85.5,
        "unit": "percentage"
      },
      "count": {
        "value": 10
      },
      "passRate": {
        "value": 90.0,
        "unit": "percentage"
      }
    }
  },
  {
    "entityId": "agent-id-456",
    "entityName": "Jane Smith",
    "metrics": {
      "averageScore": {
        "value": 92.1,
        "unit": "percentage"
      },
      "count": {
        "value": 5
      },
      "passRate": {
        "value": 100.0,
        "unit": "percentage"
      }
    }
  }
]

The Trap: Ignoring the count metric.
An agent with an averageScore of 100% based on 1 evaluation is not statistically significant. An agent with an averageScore of 80% based on 50 evaluations is a reliable trend. Your dashboard must filter out agents with count < threshold (e.g., 3 evaluations) to prevent noise. Displaying a “Perfect Score” for an agent who has only been evaluated once is misleading and damages trust in the dashboard.

4. Implementing the Polling Engine

Your application must poll this endpoint every 15 minutes. However, you must implement exponential backoff and rate limit handling.

Rate Limit Awareness

Genesys Cloud enforces rate limits per org and per client ID. For the Quality API, the limit is typically 100 requests per minute for standard orgs. If you have 100 agents and you query each individually, you will hit the limit.

The Solution: Aggregate queries.
Do not query per agent. Query per groupBy=agent for the entire org in a single call. The API returns all agents in one response. This reduces 100 API calls to 1.

Caching Strategy

Store the previous 15-minute window’s data in your local database. When the new data arrives, compare it to the previous state. Only update the dashboard if there is a change. This reduces rendering overhead on the frontend.

import requests
import time
import json

def fetch_quality_metrics(org_domain, client_id, client_secret):
    # 1. Get Token
    token_url = f"https://{org_domain}/oauth/token"
    token_payload = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret
    }
    token_response = requests.post(token_url, data=token_payload)
    access_token = token_response.json()["access_token"]

    # 2. Define Time Window (Current Day)
    from datetime import datetime, timezone
    start_time = datetime.now(timezone.utc).replace(hour=8, minute=0, second=0, microsecond=0).isoformat()
    end_time = datetime.now(timezone.utc).isoformat()

    # 3. Fetch Metrics
    metrics_url = f"https://{org_domain}/api/v2/quality/metrics"
    params = {
        "startTime": start_time,
        "endTime": end_time,
        "groupBy": "agent",
        "metrics": "averageScore,count,passRate"
    }
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    response = requests.get(metrics_url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# 4. Polling Loop
while True:
    try:
        data = fetch_quality_metrics("your-org.mygenesys.com", "client_id", "client_secret")
        # Process data: Filter by count > 3, update dashboard DB
        print(f"Fetched {len(data)} agent records at {datetime.now()}")
    except Exception as e:
        print(f"Error fetching data: {e}")
    
    # Wait 15 minutes (900 seconds)
    time.sleep(900)

The Trap: Ignoring Time Zones.
The API expects UTC. If your dashboard is in New York (EST), you must convert the startTime and endTime to UTC before making the call. If you pass local time, you will get data from the wrong day or no data at all. Always store and process time in UTC internally, then convert to local time only at the presentation layer.

5. Handling Evaluation Forms and Weighted Scores

If your organization uses multiple Evaluation Forms (e.g., one for Sales, one for Support), the averageScore metric might be misleading if you aggregate across all forms. A 100/100 on a simple form and a 80/100 on a complex form both contribute to the average.

The Solution: Segment by Evaluation Form.
Add evaluationForm to your groupBy parameter or filter by evaluationFormId in the query.

GET https://{{org_domain}}/api/v2/quality/metrics?startTime=...&endTime=...&groupBy=agent&metrics=averageScore&evaluationFormId=your-form-id

This ensures that the dashboard displays the correct score for the specific context of the agent’s role.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The “Zero Count” Ghost Agent

The Failure Condition: The dashboard displays an agent with a score of 0% or null.
The Root Cause: The agent has no evaluations in the current time window. The API may return a record with count: 0 if the agent is assigned to the queue but has not been evaluated.
The Solution: In your data processing logic, explicitly filter out any record where metrics.count.value == 0. Do not display these agents. Instead, show “No Data” or hide them until they have at least one evaluation.

Edge Case 2: The 15-Minute Lag Spike

The Failure Condition: The dashboard shows a sudden drop in scores at 9:15 AM, then recovers at 9:30 AM.
The Root Cause: This is not a data error. This is the batch processing window. If an evaluation was submitted at 9:14 AM, it may not appear in the 9:15 AM poll if the batch job was delayed.
The Solution: Communicate this latency to users. Label the dashboard as “Updated every 15 minutes” and “Data may lag by up to 30 minutes during peak load.” Do not promise second-by-second accuracy.

Edge Case 3: OAuth Token Expiry During Polling

The Failure Condition: The polling script fails with a 401 Unauthorized error after running for an hour.
The Root Cause: The access token expires after 1 hour (3600 seconds). Your script is using a stale token.
The Solution: Implement token refresh logic. Check the expires_in value from the token response. Refresh the token 5 minutes before expiry. Do not wait for the 401 error.

# Pseudocode for Token Refresh
if current_time + 300 > token_expiry_time:
    token = get_new_token()
    update_global_token(token)

Edge Case 4: Agent Name Changes

The Failure Condition: The dashboard shows two records for the same agent after a name change (e.g., “John Doe” and “J. Doe”).
The Root Cause: The API returns entityName. If you key your dashboard by name, a name change creates a duplicate.
The Solution: Always key your data by entityId (the UUID). The entityName is for display only. When you detect a name change, update the display name in your local database for the existing entityId. Do not create a new record.

Official References