Architecting Priority-Based Notification Queuing with Guaranteed Delivery SLAs

How-To-Articles
1

Architecting Priority-Based Notification Queuing with Guaranteed Delivery SLAs

What This Guide Covers

This guide details the implementation of a priority-based notification queuing system within Genesys Cloud CX that guarantees Service Level Agreement (SLA) adherence for high-priority messages while managing volume spikes for lower-priority communications. The end result is a robust architecture using Architect flows, custom attributes, and queue prioritization logic that ensures critical alerts bypass standard wait times without degrading the experience for standard notifications.

Prerequisites, Roles & Licensing

  • Licensing Tier: Genesys Cloud CX 1 or higher. Advanced WFM features are not required for the queueing logic itself, but are recommended for monitoring adherence.
  • Permissions:
    • Architect > Flow > Edit
    • Routing > Queue > Edit
    • User > User > Edit (to assign skills)
    • Reporting > Report > View
  • OAuth Scopes: If integrating via API for external triggers:
    • architect:flow:edit
    • routing:queue:edit
    • user:user:read
  • External Dependencies:
    • A reliable external trigger source (e.g., CRM webhook, IoT platform, or internal middleware) capable of sending JSON payloads to Genesys Cloud.
    • Sufficient agent capacity with the Notification-Handler skill assigned.

The Implementation Deep-Dive

1. Defining the Priority Schema and Custom Attributes

The foundation of priority-based queuing is not the queue itself, but the metadata attached to the interaction. Genesys Cloud CX allows you to pass custom attributes into an interaction via the POST /api/v2/conversations endpoint or through Architect flow logic. These attributes become the sorting keys for your prioritization engine.

We must define a strict priority schema. Avoid using arbitrary strings like “high” or “low”. Instead, use a numeric scale where lower numbers indicate higher priority. This aligns with standard sorting algorithms and simplifies the logic in the Architect flow.

The Schema:

  • priority_level: Integer (1 = Critical, 2 = High, 3 = Normal, 4 = Low)
  • sla_deadline: Timestamp (ISO 8601 format) representing the absolute maximum wait time allowed for this interaction.
  • source_system: String (for routing and reporting segmentation).

The Trap: Many architects attempt to use the built-in priority field on the interaction object. This field is often reserved for internal system use or specific carrier integrations and may not persist correctly across all channel types (voice, chat, email). Using custom attributes ensures portability and explicit control. Furthermore, failing to validate the priority_level input allows external systems to inject invalid values, causing sorting logic to fail silently.

Implementation:
In your external system, structure the payload as follows:

{
  "type": "voice",
  "wrapUpCode": null,
  "from": {
    "id": "external_system_id",
    "name": "IoT Alert System"
  },
  "to": [
    {
      "id": "queue_id_here",
      "type": "queue"
    }
  ],
  "customAttributes": {
    "priority_level": "1",
    "sla_deadline": "2023-10-27T10:00:00Z",
    "source_system": "critical_monitoring"
  }
}

When this interaction enters Genesys Cloud, the customAttributes are immediately available to the Architect flow. You must ensure the queue receiving these interactions has the Notification-Handler skill requirement, and that agents assigned to this queue have this skill.

2. Architecting the Priority Sorting Flow

We do not rely on the default queue behavior alone. Instead, we use an Architect flow to explicitly sort and manage the interaction before it enters the queue. This allows us to enforce SLA checks and apply dynamic routing strategies based on the current state of the queue.

The Flow Logic:

  1. Start Node: Receives the interaction.
  2. Set Custom Attributes: Ensure priority_level is parsed as an integer. If the attribute is missing, default to 3 (Normal).
  3. Check SLA Breach Risk: Calculate the time difference between the current time and sla_deadline. If the remaining time is less than the average handle time (AHT) plus a buffer, flag the interaction as sla_at_risk.
  4. Queue Interaction: Use the Queue node.
    • Queue: Select the target queue.
    • Priority: Map the priority_level attribute to the queue priority. Genesys Cloud supports setting the priority of an interaction in the queue node.
    • Skill: Assign the Notification-Handler skill.

The Trap: A common misconfiguration is setting the queue priority statically in the Queue node. This ignores the dynamic nature of the incoming data. You must use an expression to map the custom attribute to the queue priority field. For example, use interaction.customAttributes.priority_level in the priority field of the Queue node. If you hardcode the priority, all interactions will compete equally, negating the entire priority architecture.

Additionally, do not use the Wait node to artificially delay low-priority interactions. This consumes system resources and can lead to timeouts. Instead, rely on the queue’s internal prioritization engine, which is designed to handle large volumes of interactions efficiently.

3. Configuring Queue Prioritization and SLA Monitoring

The queue itself must be configured to respect the priority levels assigned by the Architect flow. Genesys Cloud CX queues support priority-based routing out of the box, but you must verify the settings.

Queue Configuration:

  • Routing Strategy: Set to Longest Idle Agent. This ensures that the agent who has been waiting the longest gets the next available interaction, but the interaction selection is still governed by priority.
  • Priority Handling: Ensure that the queue is set to Priority mode. In Genesys Cloud, this is implicit when you set the priority on the interaction. The system will always offer the highest priority interaction to the next available agent.

SLA Monitoring with WEM:
To guarantee SLA adherence, you must implement real-time monitoring. Use Workforce Engagement Management (WEM) to create a dashboard that tracks:

  • Average Speed of Answer (ASA) by priority_level.
  • Abandonment Rate by priority_level.
  • SLA Breach Count: Interactions where the wait time exceeded the sla_deadline.

The Trap: Relying solely on post-call reporting. By the time you see a high abandonment rate for critical alerts in the next day’s report, the damage is done. You must set up real-time alerts in WEM or use the Genesys Cloud API to monitor queue metrics every 30 seconds. If the ASA for priority_level 1 exceeds 10 seconds, trigger an escalation protocol (e.g., notify a supervisor via Teams/Slack webhook).

4. Implementing Escalation Logic for SLA Breaches

Guaranteed delivery SLAs require a fail-safe mechanism. If an interaction is at risk of breaching its SLA, the system must take proactive action. We implement this using a combination of Architect flow logic and external webhooks.

The Escalation Flow:

  1. Start Node: Triggered by a scheduled task or a real-time event from the queue.
  2. Get Queue Stats: Use the GET /api/v2/routing/queues/{queueId}/stats endpoint to retrieve current wait times.
  3. Filter Interactions: Identify interactions in the queue where current_wait_time > sla_deadline - aht_buffer.
  4. Send Notification: Use a Webhook node to send an alert to a management dashboard or chat application.
  5. Update Priority: Optionally, increase the priority of these interactions to 1 (if not already) to ensure they are offered to agents immediately.

The Trap: Over-escalating. If you escalate every interaction that is slightly over the average wait time, you will create “alert fatigue” for supervisors. Define strict thresholds. For example, only escalate if the interaction has been in the queue for more than 80% of its sla_deadline.

Furthermore, ensure that the escalation logic does not create a loop. If the webhook fails, do not retry indefinitely. Implement exponential backoff and circuit breakers in your external middleware to handle transient failures.

5. Agent Experience and Wrap-Up Handling

The agent experience is critical to maintaining SLA adherence. Agents must be aware of the priority of the interaction they are handling.

Customizing the Agent Desktop:

  • Use Custom Fields on the interaction to display the priority_level and sla_deadline prominently in the agent’s screen pop.
  • Configure Screen Pops to trigger based on the source_system attribute. For critical alerts, use a distinct visual cue (e.g., red background) to draw immediate attention.

Wrap-Up Handling:

  • Configure Wrap-Up Codes that reflect the priority of the interaction. For example, Critical-Handled, High-Handled, Normal-Handled.
  • Use Automatic Wrap-Up for low-priority interactions to ensure agents are returned to the queue quickly. For high-priority interactions, allow manual wrap-up to ensure proper documentation.

The Trap: Ignoring the impact of wrap-up time on SLA. If agents spend excessive time in wrap-up, the effective agent capacity drops, increasing wait times for all interactions. Monitor the wrap-up-duration metric by priority level. If critical interactions have longer wrap-up times, investigate whether agents are being overloaded with documentation tasks. Consider using speech analytics to automate documentation for critical alerts, reducing the manual effort required by agents.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Priority Inversion Under High Load

The Failure Condition: During peak load, high-priority interactions are delayed despite their priority setting.
The Root Cause: This is often caused by “priority inversion” where a large number of low-priority interactions occupy all available agents, and the system’s routing algorithm does not preemptively steal agents from low-priority interactions to serve high-priority ones. Genesys Cloud CX does not support agent preemption by default.
The Solution: Implement a “Priority Reservation” strategy. Reserve a subset of agents (e.g., 20% of total capacity) exclusively for high-priority interactions. Create a separate queue for priority_level 1 and 2, and assign these reserved agents to it. Use Architect logic to route high-priority interactions to this dedicated queue. This ensures that critical alerts always have immediate agent availability, regardless of the volume in the standard queue.

Edge Case 2: SLA Deadline Missed Due to Timezone Misalignment

The Failure Condition: Interactions are marked as SLA breaches even though agents handled them within the expected timeframe.
The Root Cause: The sla_deadline timestamp is sent in UTC, but the Architect flow or reporting dashboard interprets it in the local timezone of the user or the cluster. This discrepancy leads to incorrect calculations of remaining time.
The Solution: Standardize all timestamps to UTC throughout the architecture. In the Architect flow, use the now() function which returns UTC time. When comparing now() with sla_deadline, ensure both are in UTC. In reporting, use the utc modifier in SQL queries to convert timestamps to UTC before comparison. Document this requirement clearly for all external systems integrating with Genesys Cloud.

Edge Case 3: Custom Attribute Persistence Across Channels

The Failure Condition: An interaction starts as a voice call with high priority, but when transferred to chat or email, the priority is lost.
The Root Cause: Custom attributes are not automatically persisted across channel transfers unless explicitly configured. The transfer process may create a new interaction instance, discarding the original custom attributes.
The Solution: Use the Transfer node in Architect to explicitly map custom attributes from the source interaction to the target interaction. In the transfer configuration, enable the option to “Copy custom attributes”. Alternatively, use the Genesys Cloud API to update the custom attributes of the new interaction immediately after the transfer is initiated. Test this behavior thoroughly for all supported channel combinations (voice-to-chat, chat-to-email, etc.).

Official References