Implementing Real-Time Competitor Mention Detection and Retention Offer Prompt Triggers

How-To-Articles
1

Implementing Real-Time Competitor Mention Detection and Retention Offer Prompt Triggers

What This Guide Covers

This guide details the architecture for deploying real-time speech analytics to detect competitor mentions and trigger immediate, context-aware supervisor prompts and agent-side retention offers within the Genesys Cloud CX environment. By the end of this implementation, you will have a fully automated pipeline that intercepts negative sentiment or competitive threats, evaluates customer value in real-time, and pushes actionable UI widgets to the agent without interrupting the conversation flow.

Prerequisites, Roles & Licensing

To implement this solution, you must ensure the following licensing, permissions, and infrastructure components are in place. This architecture relies on the tight coupling of Genesys Cloud Speech Analytics, Architect, and the Agent Desktop API.

Licensing Requirements

  • Genesys Cloud Speech Analytics Add-on: Required for real-time transcription and entity detection.
  • Genesys Cloud CX 1 or CX 2: Required for access to Architect flows and API integrations.
  • WEM (Workforce Engagement Management) Add-on: Optional, but recommended if you intend to capture these events for quality assurance scoring later.
  • API Developer License: Required for creating the integration user and managing OAuth tokens.

Permissions & Roles

The integration user (service account) used by the middleware must have the following granular permissions assigned via a custom role:

  • Interaction > Interaction > Read
  • Interaction > Interaction > Update
  • Telephony > Call > Read
  • Analytics > Speech Analytics > Read
  • Users > User > Read (To fetch agent context if needed)

OAuth Scopes

The middleware application must request the following scopes during the OAuth token exchange:

  • urn:genesys:cloud:api:interaction:read
  • urn:genesys:cloud:api:interaction:update
  • urn:genesys:cloud:api:speech:read
  • open_id

External Dependencies

  • CRM/Middleware: A lightweight service (Node.js, Python, or Java) to act as the logic bridge between the Speech Analytics webhook and the Genesys API.
  • Customer Data Platform (CDP): Access to real-time customer tier data (e.g., “Platinum,” “Gold”) via an external API or a pre-populated Genesys Attribute.

The Implementation Deep-Dive

1. Configuring Real-Time Speech Analytics Entities and Rules

The foundation of this system is not the trigger mechanism, but the accuracy of the detection. We must configure the Speech Analytics engine to distinguish between a casual mention of a competitor and a genuine threat to churn.

Defining the Competitor Entity

Navigate to Admin > Analytics > Speech Analytics > Entities. Create a new Entity named Competitor_List.

  1. Type: Select Keyword List.
  2. Values: Add your primary competitors. Use variations to handle speech recognition errors (e.g., Verizon, Verizon Wireless, V-Zone).
  3. Case Sensitivity: Set to False.

The Trap: Do not rely on exact string matching alone. Speech-to-Text (STT) engines often misinterpret homophones or brand names. If you only add AT&T, the engine may miss AT and T or ATT. You must include phonetic variations and common misspellings in your entity list. Furthermore, do not add generic terms like “cable” or “phone” unless paired with specific competitor names, as this increases false positives significantly.

Creating the Detection Rule

Navigate to Admin > Analytics > Speech Analytics > Rules. Create a new Rule named Competitor_Threat_Detection.

  1. Condition: Set Entity to Competitor_List.
  2. Context Window: Set to 5 seconds before and after the entity. This allows the engine to capture the sentiment surrounding the mention.
  3. Sentiment Analysis: Enable Sentiment and set the threshold to Negative (score < -0.5).
  4. Speaker: Set to Customer. This prevents the rule from triggering if the agent mentions a competitor during a training call or internal discussion.

Architectural Reasoning: By filtering on Speaker: Customer and Sentiment: Negative, we reduce the noise floor. A positive mention of a competitor (e.g., “I like your service better than Competitor X”) is not a retention risk. We only care when the customer is dissatisfied and referencing alternatives.

Enabling Real-Time Streaming

In the Rule configuration, ensure Real-Time is enabled. This pushes the event to the webhook endpoint immediately upon detection, rather than waiting for the call to end. Set the Webhook URL to your middleware service endpoint (e.g., https://api.yourdomain.com/webhooks/genesys/speech).

2. Building the Middleware Logic Engine

The Genesys Cloud platform does not natively support complex business logic decision trees within the Speech Analytics webhook receiver. We must build a lightweight middleware service to evaluate the customer’s value and determine the appropriate retention offer.

The Webhook Handler

Your middleware must accept the POST request from Genesys. The payload will contain the Interaction ID, User ID (Agent), and the detected Entity and Sentiment data.

Example Incoming Payload (Simplified):

{
  "event": "speech.analytics.detection",
  "data": {
    "interactionId": "i-12345678-1234-1234-1234-123456789012",
    "userId": "u-agent-jane-doe",
    "timestamp": "2023-10-27T10:00:00Z",
    "entities": [
      {
        "name": "Competitor_List",
        "value": "Verizon",
        "confidence": 0.92
      }
    ],
    "sentiment": {
      "score": -0.75,
      "label": "Negative"
    }
  }
}

The Decision Logic

Upon receiving the payload, the middleware must perform the following steps:

  1. Fetch Customer Context: Use the interactionId to query the Genesys API for the associated External Contact ID or Account ID.
  2. Query CRM: Call your CRM/CDP API to retrieve the customer’s tier (e.g., Platinum, Gold, Silver).
  3. Determine Offer:
    • If Tier == Platinum and Competitor == Verizon: Offer 10% Discount for 12 Months.
    • If Tier == Gold and Competitor == AT&T: Offer Free Upgrade to Premium Support.
    • If Tier == Silver: No automatic offer; flag for Supervisor Review only.

The Trap: Do not perform heavy database queries or complex CRM lookups in the webhook handler. The Genesys webhook expects a 200 OK response within 5 seconds. If your middleware takes 10 seconds to query the CRM, Genesys will mark the webhook as failed and retry, potentially causing duplicate prompts. Use an asynchronous queue (e.g., AWS SQS, RabbitMQ) to handle the CRM lookup and offer generation. Return 200 OK immediately to Genesys, then process the logic in the background worker.

Generating the Prompt

Once the offer is determined, the middleware must push a prompt to the agent. We will use the Genesys Cloud Interaction Update API to attach a structured data object to the active interaction. This object will be consumed by the Agent Desktop widget.

API Call: Update Interaction

  • Method: PATCH
  • Endpoint: /api/v2/interactions/{interactionId}
  • Headers: Authorization: Bearer <token>, Content-Type: application/json

Payload:

{
  "attributes": {
    "retentionPrompt": {
      "triggered": true,
      "offerType": "discount",
      "offerDetails": "10% Discount for 12 Months",
      "competitorMentioned": "Verizon",
      "sentimentScore": -0.75,
      "timestamp": "2023-10-27T10:00:05Z"
    }
  }
}

Architectural Reasoning: We store the prompt in the interaction attributes rather than sending a direct notification (like an email or SMS) to the agent. This keeps the context tied to the specific interaction. If the agent switches calls, the prompt disappears. If the supervisor joins the call, they can see the history of prompts triggered. This is critical for auditability and coaching.

3. Developing the Agent Desktop Widget

The agent needs a non-intrusive way to see the prompt. We will build a simple Genesys Cloud UI Plugin that monitors the active interaction for changes in the retentionPrompt attribute.

Widget Structure

The widget should display:

  1. Alert Banner: A yellow/red banner at the top of the interaction panel.
  2. Offer Details: The specific offer text.
  3. Accept/Decline Buttons: To track agent compliance.

Monitoring for Changes

Use the Genesys Cloud SDK or REST API polling to watch for attribute updates.

Example Polling Logic (Pseudo-code):

// Poll every 2 seconds for active interaction
setInterval(async () => {
  const activeInteraction = await getActiveInteraction();
  if (activeInteraction && activeInteraction.attributes.retentionPrompt) {
    const prompt = activeInteraction.attributes.retentionPrompt;
    if (prompt.triggered && !hasDisplayed(prompt.timestamp)) {
      displayPrompt(prompt);
      markAsDisplayed(prompt.timestamp);
    }
  }
}, 2000);

The Trap: Do not use a simple alert() box. This blocks the UI and forces the agent to click “OK” before they can continue typing or speaking. This breaks the conversation flow and increases handle time. Use a non-blocking modal or a slide-in panel that allows the agent to acknowledge the prompt while continuing the call.

Tracking Agent Action

When the agent clicks “Accept Offer,” the widget must send a PATCH request to the interaction to log the action.

API Call: Update Interaction (Agent Action)

  • Method: PATCH
  • Endpoint: /api/v2/interactions/{interactionId}

Payload:

{
  "attributes": {
    "retentionPrompt": {
      "triggered": true,
      "agentAction": "accepted",
      "actionTimestamp": "2023-10-27T10:00:15Z"
    }
  }
}

This data is crucial for downstream analytics. You can now measure the conversion rate of real-time prompts versus post-call follow-ups.

4. Supervisor Oversight and Escalation

Not all mentions should be handled by the agent. Some customers require immediate supervisor intervention. We will configure a secondary rule in Speech Analytics for high-value customers with extreme negative sentiment.

High-Priority Rule

Create a new Speech Analytics Rule named High_Value_Escalation.

  1. Condition: Entity = Competitor_List AND Sentiment < -0.8 AND Customer_Tier = Platinum.
  2. Action: Trigger a Real-Time Alert to the Supervisor’s dashboard.

Supervisor Dashboard Integration

Use the Genesys Cloud Supervisor Dashboard to create a custom widget that lists all active interactions with the High_Value_Escalation flag. This allows supervisors to jump into the call and assist the agent immediately.

The Trap: Do not automatically transfer the call to the supervisor. This is jarring for the customer and disrupts the agent. Instead, allow the supervisor to “Barge In” or “Whisper” to the agent. Give the agent control over the escalation. The prompt should say, “Supervisor available for assistance. Click to invite.”

Validation, Edge Cases & Troubleshooting

Edge Case 1: The “Double-Dip” Prompt

The Failure Condition: The agent receives two identical prompts for the same competitor mention within a 10-second window.
The Root Cause: The Speech Analytics engine sometimes emits multiple events for the same entity if the customer repeats the word or if the STT engine re-evaluates the transcript. Additionally, the webhook retry mechanism may fire if the middleware was slow to respond initially.
The Solution: Implement an idempotency key in your middleware. Use the interactionId combined with the entityValue and a time window (e.g., 60 seconds) as a unique key. If a prompt has already been sent for this interaction/entity within the window, discard the duplicate event.

Edge Case 2: The “Silent” Agent

The Failure Condition: The agent ignores the prompt, and the customer eventually churns.
The Root Cause: The prompt was too intrusive, too vague, or the agent did not trust the offer.
The Solution: A/B test the prompt UI. Test different colors, positions, and offer phrasings. Also, ensure the offer is actually valid. If the agent clicks “Accept” and the CRM system rejects the discount due to policy, the agent will lose trust in the tool. Your middleware must validate the offer against CRM rules before pushing it to the agent.

Edge Case 3: Latency Spikes

The Failure Condition: The prompt appears 30 seconds after the competitor mention.
The Root Cause: The middleware queue is backed up, or the Genesys API is experiencing high latency.
The Solution: Monitor the end-to-end latency from Speech Analytics detection to Widget display. Set up alerts if the median latency exceeds 10 seconds. If latency is high, consider degrading gracefully: instead of a real-time prompt, flag the call for post-call review and send the agent a summary after the call ends.

Edge Case 4: False Positive on Internal Calls

The Failure Condition: The system triggers a retention prompt during an internal training call where the trainer mentions a competitor.
The Root Cause: The Speech Analytics rule was not scoped to exclude internal queues or specific agent groups.
The Solution: In the Speech Analytics Rule configuration, add a condition to exclude interactions where Queue Name contains “Training” or “Internal”. Alternatively, exclude specific user groups from real-time analytics processing.

Official References