Implementing Customer Intent Prediction Overlays Displayed in the Agent Desktop Sidebar

How-To-Articles
1

Implementing Customer Intent Prediction Overlays Displayed in the Agent Desktop Sidebar

What This Guide Covers

This guide details the architectural implementation of real-time customer intent prediction overlays within the Genesys Cloud CX Agent Desktop. You will configure a machine learning model to analyze inbound call transcripts or chat messages, determine the customer’s probable intent, and push a structured JSON payload to a custom HTML5 Sidebar Application. The result is a dynamic UI element that appears alongside the agent’s active interaction, providing immediate context, suggested next best actions, and relevant knowledge base articles based on the predicted intent.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Genesys Cloud CX 2 or CX 3: Required for access to the Architect module, Engagement Analytics, and Machine Learning capabilities (specifically the Text Analytics or Conversation Analytics engines).
  • Developer Add-on: Required to build and deploy custom Sidebar Applications and manage OAuth credentials for backend services.
  • Interaction Analytics Add-on: If using historical interaction data to train the intent model via the Genesys Cloud ML API.

Permissions & Roles

The following permissions are required for the deployment team:

  • Architect: routing:architect:view, routing:architect:edit (to configure flow logic and data attributes).
  • Administration: admin:application:edit (to register the Sidebar App), admin:oauthclient:edit (to manage API credentials).
  • Security: security:role:edit (to assign permissions to the agent-facing role if the sidebar requires specific data visibility).
  • API Access: An OAuth Client with the scopes:
    • analytics:interactions:view (to fetch real-time transcript data).
    • routing:interaction:view (to access interaction context).
    • conversation:analytics:view (if using Conversation Analytics intents).

External Dependencies

  • Backend Intent Service: A cloud-hosted service (AWS Lambda, Azure Function, or Genesys Cloud Integration) capable of receiving a webhook, processing text, and returning a JSON response. This guide assumes a custom microservice, but the pattern applies equally to pre-built NLP providers like Google Dialogflow or AWS Comprehend.
  • Frontend Framework: Familiarity with the Genesys Cloud Sidebar SDK (@genesyscloud/purecloud-sidebar-sdk).

The Implementation Deep-Dive

1. Architecting the Data Flow and Intent Model

The foundation of this implementation is not the UI, but the data pipeline. The Agent Desktop Sidebar is a passive consumer of data. It does not poll for intent; it waits for an event or a state change. Therefore, the architecture must push the intent prediction to the frontend context.

The Architect Flow Configuration

You must intercept the interaction within the Architect module before it reaches the agent, or immediately upon connection, to trigger the intent analysis.

  1. Capture Interaction Context: Use the Get Interaction Details block to retrieve the interaction.id, type (Voice/Chat), and customer attributes.
  2. Transcript/Message Extraction:
    • For Chat: The initial message is available immediately. Extract the message.text attribute.
    • For Voice: You cannot analyze speech until it is transcribed. You must use the Get Transcript block or rely on the Conversation Analytics webhook. Critical Decision: Real-time voice intent is latency-sensitive. If you rely on full-call transcription, the intent overlay will appear too late. Instead, configure the Architect flow to trigger the intent service on the first 10-15 seconds of speech or upon specific keyword detection using the Speech Recognition block.
  3. Invoke Intent Service: Use the Make HTTP Request block to send the extracted text to your external Intent Service endpoint.

The Trap: Synchronous Blocking
A common misconfiguration is using the Make HTTP Request block in a synchronous manner that blocks the call flow while waiting for the NLP service to respond. If the NLP service takes 2 seconds to process, the customer hears silence.

  • The Fix: Use an Asynchronous pattern. Send the text to the NLP service via a webhook (fire-and-forget) or use the Make HTTP Request block with a short timeout (e.g., 500ms) and a fallback path. If the intent is not ready when the agent answers, the Sidebar should display a “Loading” state or default information, and update once the intent arrives via a WebSocket or REST API callback to the frontend.

Defining the JSON Payload Structure

Your Intent Service must return a standardized JSON structure. This structure dictates what the Sidebar displays.

{
  "interactionId": "i-12345678-1234-1234-1234-123456789012",
  "timestamp": "2023-10-27T10:00:00Z",
  "predictions": [
    {
      "intent": "billing_inquiry",
      "confidence": 0.92,
      "category": "Finance",
      "suggestedActions": [
        {
          "label": "View Invoice History",
          "type": "link",
          "url": "/crm/invoices/{customerId}"
        },
        {
          "label": "Apply Waiver",
          "type": "button",
          "apiAction": "POST /api/waivers"
        }
      ],
      "knowledgeArticles": [
        {
          "title": "Understanding Your Monthly Statement",
          "url": "https://kb.company.com/article/123"
        }
      ]
    }
  ],
  "sentiment": "frustrated"
}

Architectural Reasoning: We include suggestedActions with type and url/apiAction to allow the Sidebar to be interactive. The Sidebar is not just a display; it is a control plane extension. By defining the action type, the frontend can render a clickable link or a button that triggers a backend API call directly from the browser.

2. Building the Sidebar Application Frontend

The Sidebar Application is a standard single-page application (SPA) that integrates with the Genesys Cloud Sidebar SDK. It runs inside an iframe within the Agent Desktop.

Step 1: Initialize the Sidebar SDK

Create a React, Angular, or Vue application. Install the Genesys Cloud Sidebar SDK.

npm install @genesyscloud/purecloud-sidebar-sdk

In your main component, initialize the SDK to establish the communication channel with the Agent Desktop.

import { SidebarSdk } from '@genesyscloud/purecloud-sidebar-sdk';

const sdk = new SidebarSdk();
const { client, interactions } = sdk;

// Subscribe to interaction changes
sdk.interactions.on('interactionChanged', (interaction) => {
  if (interaction && interaction.type === 'voice') {
    fetchIntentForInteraction(interaction.id);
  }
});

Step 2: Implementing the Intent Fetcher

The fetchIntentForInteraction function is the bridge between the SDK and your backend.

async function fetchIntentForInteraction(interactionId) {
  try {
    // Call your internal API gateway which proxies to the Intent Service
    const response = await fetch(`/api/intent/predict?interactionId=${interactionId}`);
    const data = await response.json();
    
    // Update the local state to render the UI
    setIntentData(data);
  } catch (error) {
    console.error('Failed to fetch intent', error);
    setIntentData(null);
  }
}

The Trap: Cross-Origin Resource Sharing (CORS)
The Sidebar runs in an iframe. If your Intent Service is hosted on a different domain than the Sidebar application, you must configure CORS headers correctly. More importantly, the Agent Desktop injects specific headers. If you enforce strict Access-Control-Allow-Origin policies without whitelisting the Genesys Cloud domain (https://*.mypurecloud.com), the request will fail silently.

  • The Fix: Configure your API Gateway or Reverse Proxy to allow origins from https://*.mypurecloud.com and include the Authorization header in the Access-Control-Allow-Headers list if you are passing OAuth tokens.

Step 3: Rendering the Overlay

Use the intentData state to render the UI. The design should be non-intrusive. Use Genesys Cloud’s Design System (@genesyscloud/design-system) to ensure visual consistency.

import { Box, Card, Button, Text } from '@genesyscloud/design-system';

function IntentOverlay({ intentData }) {
  if (!intentData) return <LoadingState />;

  return (
    <Box padding="spacing-020">
      <Card>
        <Text variant="text-050" color="color-text-default">
          Predicted Intent: {intentData.predictions[0].intent}
        </Text>
        <Text variant="text-040" color="color-text-secondary">
          Confidence: {(intentData.predictions[0].confidence * 100).toFixed(0)}%
        </Text>
        
        <Box marginTop="spacing-020">
          {intentData.predictions[0].suggestedActions.map((action, index) => (
            <Button
              key={index}
              variant="primary"
              onClick={() => handleAction(action)}
            >
              {action.label}
            </Button>
          ))}
        </Box>
      </Card>
    </Box>
  );
}

Architectural Reasoning: We separate the data fetching logic from the UI rendering. This allows the Sidebar to remain responsive even if the intent service is slow. The LoadingState component should be lightweight to prevent layout shifts.

3. Integrating with Genesys Cloud Analytics and Workflows

To make the intent prediction actionable, it must be tied to Genesys Cloud’s core workflows.

Writing Back to the Interaction

When an agent clicks a “Suggested Action” in the Sidebar, the action should be logged in the interaction transcript for compliance and analytics.

  1. Add Data to Interaction: Use the Update Interaction Data block in Architect or the routing:interaction:edit API scope in your backend service.
  2. Custom Attributes: Store the intent prediction in a custom attribute on the interaction.
    • Key: intent_prediction
    • Value: billing_inquiry
    • Key: intent_confidence
    • Value: 0.92

This allows you to create reports in Analytics to measure the accuracy of the intent model over time. You can create a dashboard that filters interactions by intent_prediction and correlates them with handle_time and customer_satisfaction_score.

Dynamic Routing Based on Intent

If the intent is determined before the agent is selected (e.g., in the IVR or Chat Entry), you can use the intent to route the interaction to a specialized queue.

  1. Architect Flow: After receiving the intent from the NLP service, use a Decision block.
  2. Condition: intent_prediction == "billing_inquiry"
  3. Action: Route to Queue: Billing Specialists.
  4. Sidebar Integration: The Sidebar will still display the intent, but now the agent is already in the correct queue. This reduces handle time by ensuring the agent has the specific skills required for the predicted intent.

The Trap: Routing Latency
If you route based on real-time intent, you add latency to the queue entry. If the NLP service is slow, the customer waits in the IVR longer.

  • The Fix: Use a two-stage routing strategy. First, route to a general queue based on IVR input. Then, once the intent is confirmed via transcript analysis, use Workforce Management (WFM) skills or Queue Priority to prioritize the interaction for agents with the matching skill set, rather than changing the queue entirely.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Low Confidence Predictions

The Failure Condition: The NLP service returns an intent with a confidence score of 0.45. The Sidebar displays “Billing Inquiry” with 45% confidence. The agent acts on this information, but the customer is actually asking about technical support. This leads to agent frustration and potential misrouting.

The Root Cause: The NLP model is undertrained for ambiguous phrases, or the input text is too short/noisy.

The Solution: Implement a confidence threshold in the Sidebar logic.

if (intentData.predictions[0].confidence < 0.7) {
  setIntentData(null); // Hide the overlay
}

Alternatively, display a “Low Confidence” warning banner instead of hiding the data entirely, allowing the agent to use their judgment. You can also log these low-confidence events to retrain the model.

Edge Case 2: Voice Transcription Lag

The Failure Condition: For voice interactions, the transcript is not available until the call ends or the speech recognition engine buffers a significant amount of audio. The Sidebar shows “No Intent” for the first 30 seconds of the call.

The Root Cause: Real-time speech-to-text streaming is not enabled or configured correctly in the Architect flow.

The Solution: Enable Real-Time Speech Recognition in the Architect flow. Configure the Speech Recognition block to stream partial transcripts. Your Intent Service should accept partial transcripts and update the prediction incrementally. The Sidebar should listen for multiple updates from the backend via Server-Sent Events (SSE) or WebSocket, updating the UI as confidence increases.

Edge Case 3: Sidebar App Crash or Unavailability

The Failure Condition: The custom Sidebar application fails to load due to a JavaScript error or a backend API outage. The agent sees a blank space or an error message in the sidebar, which is distracting.

The Root Cause: Lack of error handling in the frontend SDK initialization or backend API failure.

The Solution: Implement a robust error boundary in the React/Vue application. If the Sidebar fails to load, it should gracefully degrade to a simple “Support” link or hide itself entirely. Use the Sidebar SDK’s hide method to remove the app from the desktop if it cannot function.

sdk.ui.on('error', (error) => {
  console.error('Sidebar Error', error);
  sdk.ui.hide(); // Hide the broken sidebar
});

Official References