Implementing Multi-Channel Achievement Notifications via WEM API and Admin Console

How-To-Articles
1

Implementing Multi-Channel Achievement Notifications via WEM API and Admin Console

What This Guide Covers

You are configuring Genesys Cloud WEM Achievements to deliver completion notifications through Desktop Toasts, Email, and Mobile Push. The end result is a deterministic notification pipeline where agents receive immediate visual feedback on the desktop, a persistent email receipt, and actionable push notifications on mobile devices, with architectural controls to prevent notification fatigue and delivery failures.

Prerequisites, Roles & Licensing

  • Licensing: WEM add-on license is required. Achievements are a core feature of WEM. Agents must have a seat license that includes WEM access.
  • Roles & Permissions:
    • Role: WEM Admin or a custom role with granular permissions.
    • Permissions: wem:achievement:write, wem:achievement:read, wem:achievement:read:all.
  • OAuth Scopes:
    • wem:achievement:write (Required for API creation/update).
    • wem:achievement:read (Required for validation).
  • External Dependencies:
    • Genesys Desktop: Installed and running on agent workstations. Minimum version must support WEM toast rendering.
    • Genesys Cloud Mobile App: Installed on iOS/Android devices with notification permissions granted.
    • Email Relay: If custom from_email addresses are used, the organization must verify the domain or configure a relay that permits the WEM service account.

The Implementation Deep-Dive

1. Achievement Definition and Notification Schema Construction

The notification behavior is metadata bound to the Achievement object. We do not configure notifications as independent entities; they are properties of the achievement definition. This coupling ensures that notification settings travel with the achievement through version control and environment promotions.

We construct the achievement payload using the WEM Achievements API. The notifications object within the payload dictates the delivery channels. We must explicitly define each channel. Relying on defaults is an anti-pattern because tenant defaults can change, and defaults do not guarantee consistency across development, staging, and production environments.

Architectural Reasoning:
We use the API for definition rather than the UI when deploying at scale or integrating with external gamification engines. The API provides atomic control over the notification schema. The UI often obscures the granular control over email subjects and push payloads, leading to generic notifications that agents ignore. By defining the schema via API, we enforce branding and include dynamic variables (e.g., {achievement_name}, {agent_name}) that increase engagement.

The Trap:
Misconfigured Completion Scope causing Evaluation Loops.
If you define a trigger based on a metric that updates frequently (e.g., calls_handled) and set a completion condition of >= 10, the WEM evaluation engine checks this condition on every metric update. While WEM prevents duplicate achievement completions, the evaluation overhead can degrade performance under high load. More critically, if the scope is not bounded by a time window or a Once type, agents may accumulate achievement points without receiving notifications because the engine assumes the achievement is “in progress” rather than “completed” until the scope closes.
Mitigation: Always define a scope_type (e.g., DAILY, WEEKLY, or ONCE). Use ONCE for milestone achievements and time-bound scopes for recurring achievements. This ensures the evaluation engine has a deterministic end state to trigger the notification pipeline.

API Payload Example:

POST /api/v2/wem/achievements
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "name": "First Contact Resolution Master",
  "description": "Awarded for resolving 50 calls on first contact.",
  "type": "ACHIEVEMENT",
  "completion_type": "ONCE",
  "scope_type": "ALL_TIME",
  "trigger": {
    "metric_id": "metric_fcr_count",
    "condition": {
      "operator": "GTE",
      "value": 50
    }
  },
  "notifications": {
    "toast": true,
    "email": {
      "enabled": true,
      "subject": "Achievement Unlocked: {{achievement.name}}",
      "body": "Congratulations {{agent.name}}! You have earned {{achievement.name}}. View details in the WEM dashboard."
    },
    "push": {
      "enabled": true,
      "title": "Achievement Unlocked!",
      "body": "You earned {{achievement.name}}"
    }
  }
}

2. Desktop Toast Delivery and WebSocket Persistence

Desktop toasts are rendered by the Genesys Desktop application via a persistent WebSocket connection to the Genesys Cloud notification service. The WEM engine publishes a completion event to the internal event bus, which the notification service routes to the agent’s active sessions.

Architectural Reasoning:
We treat toasts as real-time, ephemeral feedback. The architecture assumes the agent is logged into Desktop. Toasts provide immediate reinforcement, which is critical for behavioral conditioning. We configure toasts to be enabled by default because the latency of email or push is too high to support the “moment of achievement.” The WebSocket mechanism ensures sub-second delivery, provided the client connection is healthy.

The Trap:
Client-Side Notification Suppression and Version Drift.
Agents can disable WEM toasts within the Desktop application settings (Settings > Notifications > WEM). If you assume the toast will appear because the API flag is true, you will encounter “silent failures” where the backend sends the notification, but the client discards it. Additionally, older Desktop versions may not render the new toast schema or deep links correctly.
Mitigation: Implement a validation step in your deployment pipeline that checks for minimum Desktop version requirements. Furthermore, design your WEM program to include a “Notification Health” check. You can use the WEM Analytics API to compare achievement_completions against notification_delivery_logs (available via debug traces or admin reporting) to identify agents with suppressed notifications. Educate agents that disabling toasts breaks the gamification feedback loop.

3. Email Routing, Templating, and Relay Configuration

Email notifications serve as a persistent record and a re-engagement channel. The WEM engine queues emails for delivery via the Genesys Cloud email relay infrastructure.

Architectural Reasoning:
We configure email notifications with dynamic subject lines and bodies. Static text leads to high spam filter rates and low open rates. By injecting variables like {{agent.name}} and {{achievement.points}}, we increase relevance. We also leverage the from_email configuration at the organization level to ensure the sender identity matches the brand. If the organization uses a custom relay, we must ensure the WEM service account is authorized to send from the configured domain.

The Trap:
Email Queue Saturation and Delayed Delivery.
WEM email notifications are transactional but queued. During high-volume events (e.g., a global achievement unlocked by 5,000 agents simultaneously), the email queue can experience backpressure. This results in emails arriving minutes or hours after the achievement is earned. If an agent checks email immediately after earning an achievement and sees nothing, they may perceive the system as broken.
Mitigation: Architect your achievement triggers to avoid synchronized mass completions. Stagger achievement thresholds or use randomized time windows for recurring achievements. For critical notifications, rely on Toast and Push as the primary channels and treat email as a secondary receipt. If you must send mass emails, verify your organization’s email relay throughput limits and consider implementing a rate-limiting strategy in the achievement definition logic if supported, or splitting achievements into cohorts.

API Payload Update for Email Customization:

PATCH /api/v2/wem/achievements/{achievementId}
Content-Type: application/json

{
  "notifications": {
    "email": {
      "enabled": true,
      "subject": "New Achievement: {{achievement.name}}",
      "body": "Hi {{agent.name}},\n\nYou just unlocked {{achievement.name}} with {{achievement.points}} points.\n\n[View Achievement]"
    }
  }
}

4. Mobile Push Token Lifecycle and Deep Linking

Mobile push notifications are delivered via Firebase Cloud Messaging (FCM) for Android and Apple Push Notification service (APNs) for iOS. The Genesys Cloud Mobile app registers a device token with the platform. When an achievement completes, the notification service pushes a payload to the token.

Architectural Reasoning:
We enable push notifications to reach agents who are away from their desktops or in break rooms. The push payload must include a deep link to the WEM dashboard or the specific achievement detail. Without a deep link, the agent taps the notification and lands on the app home screen, forcing them to navigate manually. This friction reduces engagement. We configure the push payload to open the WEM module directly.

The Trap:
Stale Device Tokens and OS-Level Permission Revocation.
Device tokens expire or become invalid when the app is reinstalled, the OS is updated, or the user clears app data. If the WEM engine attempts to push to a stale token, the delivery fails silently. Additionally, users can revoke notification permissions at the OS level. The trap is assuming that enabling push in the achievement definition guarantees delivery.
Mitigation: The Genesys Cloud platform handles token cleanup automatically, but you must monitor push delivery rates. Use the WEM Analytics to track push delivery success. Educate agents to keep notification permissions enabled. Design the mobile experience so that tapping a push notification that fails to deep link (due to app state) gracefully falls back to the WEM home screen rather than crashing or doing nothing.

5. Rate Limiting and Notification Fatigue Mitigation

High-frequency notifications degrade user experience and lead to notification blindness. Agents may disable notifications entirely if they perceive them as spam.

Architectural Reasoning:
We implement rate limiting at the achievement definition level and through trigger logic. WEM provides mechanisms to control notification frequency. We configure achievements to notify only on the first completion within a scope, or we use the notification_interval settings if available. For recurring achievements, we ensure that the notification is not sent for every single increment but only upon scope completion.

The Trap:
Metric Volatility Causing Rapid-Fire Notifications.
If an achievement is tied to a volatile metric that fluctuates around the threshold (e.g., avg_handle_time < 120), and the metric dips below and rises above repeatedly, the achievement may complete and reset multiple times in a short period. This can trigger multiple notifications if the scope allows it.
Mitigation: Use hysteresis in your metric definitions or ensure achievement scopes are strictly time-bound. Avoid ONCE scopes for volatile metrics unless the metric is strictly cumulative. Configure the achievement to require a sustained condition rather than a momentary threshold breach. Review the achievement logic to ensure that notification triggers align with meaningful agent behaviors, not transient data noise.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The Silent Failure on Desktop Client Disconnect

Failure Condition:
An agent earns an achievement, but the Desktop toast does not appear. The agent is logged out of Desktop or the network connection dropped momentarily.

Root Cause:
The WebSocket connection is broken. The notification service buffers the notification for a limited window. If the agent does not reconnect within the buffer window, the toast is dropped. The email and push may still deliver, but the real-time toast is lost.

Solution:
Verify the agent’s Desktop connection status. Check the WEM notification logs for delivery status. If the toast is critical, configure the achievement to also send a push notification. Train agents to keep Desktop running and connected. Use the WEM API to query recent completions and manually verify if the notification was sent.

Edge Case 2: Push Token Invalidation and Stale Endpoints

Failure Condition:
Agents report missing push notifications. The WEM dashboard shows achievements completed, but no push is received on mobile.

Root Cause:
The device token registered with Genesys Cloud is stale. This often occurs after an app update or OS upgrade. The platform may still attempt to deliver to the old token, resulting in a silent failure.

Solution:
Have agents reinstall the Genesys Cloud Mobile app or toggle notification permissions in OS settings to force a token refresh. Monitor the push delivery metrics in WEM Analytics. If delivery rates drop significantly, investigate platform-wide token health. Ensure the mobile app version is up to date, as older versions may not register tokens correctly.

Edge Case 3: Email Queue Saturation During Peak Achievement Events

Failure Condition:
A global achievement is unlocked, and agents report emails arriving hours later or not at all.

Root Cause:
The email relay is saturated due to the volume of notifications. The WEM email queue is backlogged. This can also occur if the from_email domain is flagged by spam filters due to sudden volume spikes.

Solution:
Review the email relay configuration and throughput limits. Implement rate limiting on achievement triggers to stagger completions. Use Toast and Push as primary channels for real-time alerts. If emails are critical, configure a dedicated email relay for WEM notifications with higher throughput limits. Monitor email delivery logs for bounce rates and spam complaints.

Official References