Implementing Video Chat Handoffs from Web Messaging Interactions

How-To-Articles
1

Implementing Video Chat Handoffs from Web Messaging Interactions

What This Guide Covers

This guide configures a media upgrade path within Genesys Cloud CX where an active Web Messaging interaction transitions to a Video Chat session without terminating the contact or requiring a new queue entry. The end result is a seamless handoff where the customer clicks a video upgrade button in the web widget, the Architect flow validates agent capability, and the agent desktop renders the video pane with full session continuity and analytics tracking.

Prerequisites, Roles & Licensing

  • Licensing: CX 2 or higher for both agents and users. Video Chat functionality is not available on CX 1. Web Messaging is available on CX 1, but the handoff requires the higher tier for the video media type.
  • Permissions:
    • Video > Video Chat > Edit
    • Messaging > Web Messaging > Edit
    • Architect > Flow > Edit
    • Routing > Queue > Edit
  • OAuth Scopes: webchat:send, videochat:send, architect:flow:edit, routing:queue:edit.
  • External Dependencies:
    • Genesys Cloud Web Messaging SDK version 4.0 or higher.
    • Browser support for WebRTC (Chrome 90+, Safari 14+, Firefox 90+).
    • Queue configuration enabling both webChat and videoChat media types.

The Implementation Deep-Dive

1. Web Messaging SDK Configuration for Media Upgrade

The client-side Web Messaging SDK must explicitly signal support for media upgrades. The default SDK configuration disables media upgrades to conserve bandwidth and simplify the user interface. You must override this default during initialization.

Configuration Payload:
When initializing the genesys-cloud-web-messaging-sdk, inject the allowMediaUpgrade flag and define the supported media types. This configuration is passed to the genesys.init method or the equivalent configuration object.

{
  "deploymentId": "YOUR_DEPLOYMENT_ID",
  "allowMediaUpgrade": true,
  "mediaTypes": ["chat", "video"],
  "videoChat": {
    "enableVideo": true,
    "enableAudio": true,
    "cameraConstraints": {
      "width": { "ideal": 1280 },
      "height": { "ideal": 720 }
    }
  }
}

The Trap: Omitting allowMediaUpgrade: true or failing to include video in the mediaTypes array.
Downstream Effect: The SDK renders the chat interface but suppresses the video upgrade button. Even if the Architect flow attempts to trigger a video upgrade via the Send Message block, the client rejects the request because the SDK manifest does not advertise video capability. The flow transitions to an error state, and the customer sees a generic “Message failed to send” notification.

Architectural Reasoning: The Genesys Cloud platform enforces a capability negotiation model. The server cannot force a media upgrade if the client manifest does not support the target media type. This prevents routing video sessions to legacy browsers or mobile clients where the video widget is not embedded. The configuration ensures that the Send Message block with Media Type: Video receives a positive acknowledgment from the client.

2. Architect Flow Design and Block Configuration

The flow must handle the transition from text to video while preserving the contact context. The critical mechanism is the Send Message block configured to request a media upgrade, followed by the Video Chat block that establishes the WebRTC session.

Flow Structure:

  1. Web Messaging Trigger: The flow starts with a Web Messaging trigger.
  2. Video Upgrade Request: Use a Send Message block.
    • Set Media Type to Video.
    • Set Message Content to the prompt displayed to the customer before the upgrade (e.g., “Upgrading to video…”).
    • Enable Wait for Response.
  3. Video Chat Block: Use the Video Chat block.
    • Map Queue ID to the target queue.
    • Map Contact ID to the existing contact variable to maintain session continuity.
    • Configure Timeout appropriately for video negotiation.

Send Message Block JSON Configuration:
When editing the flow via the API or JSON export, verify the send-message block configuration. The mediaType field is the discriminator for the upgrade.

{
  "id": "send-message-upgrade",
  "type": "send-message",
  "configuration": {
    "mediaType": "video",
    "message": "Upgrading to video session. Please accept the camera request.",
    "waitForResult": true,
    "resultVariableName": "videoUpgradeResult"
  }
}

The Trap: Using a Transfer or Route to Queue block instead of the Video Chat block after the upgrade request.
Downstream Effect: A Route to Queue block attempts to create a new interaction or requeue the contact based on the current media type. If the media type has not formally switched to video in the platform state, the route may fail or drop the customer back into the web messaging queue. The Video Chat block is required to bind the WebRTC session to the existing contact ID. Using a route block breaks the session link, resulting in a duplicate contact record and loss of transcript history.

Architectural Reasoning: The Video Chat block performs the state mutation that converts the contact media type from webChat to videoChat. This mutation updates the interaction record in real time. The block also handles the signaling exchange between the Genesys Cloud media servers and the client SDK. Routing blocks do not perform media state mutations; they only direct traffic. Therefore, the media upgrade must occur within a dedicated media block that supports type conversion.

3. Queue Media Type and Skill Alignment

The target queue must support both Web Messaging and Video Chat media types. If the queue is configured for Web Messaging only, the platform rejects the video upgrade request during the flow execution.

Queue Configuration via API:
Use the PUT /api/v2/queues/{queueId} endpoint to verify and update media types. The mediaTypes array must include both values.

PUT /api/v2/queues/{queueId}
Content-Type: application/json

{
  "name": "Support - Video Enabled",
  "mediaTypes": ["webChat", "videoChat"],
  "skillRequirements": {
    "webChat": {
      "skills": [
        {
          "skill": { "id": "skill-chat-support" },
          "level": 1
        }
      ]
    },
    "videoChat": {
      "skills": [
        {
          "skill": { "id": "skill-video-support" },
          "level": 1
        }
      ]
    }
  }
}

The Trap: Assigning agents to the queue with Chat skills but omitting Video skills, or vice versa.
Downstream Effect: The flow routes the contact to the queue, but the routing engine cannot find an available agent with the required Video skill. The interaction enters the queue as a video contact, but agents with only Chat skills ignore it. The customer experiences a “Holding” state indefinitely, or the interaction abandons after the timeout. Analytics show a spike in queue wait times with zero agent acceptance.

Architectural Reasoning: Genesys Cloud routing evaluates skill requirements per media type. When the contact upgrades to video, the routing engine re-evaluates agent availability based on videoChat skill requirements. If the agent lacks the video skill, the routing engine excludes them from the candidate pool. This separation allows organizations to tier agents based on video capability. You must ensure that agents intended to handle handoffs possess both skill sets, or design the flow to route to a secondary queue dedicated to video-capable agents.

4. Agent Desktop Widget and Workspace Configuration

The agent desktop must render the video pane immediately upon the media upgrade. If the workspace is configured to show only the chat widget, the agent sees a frozen text interface while the backend processes the video session.

Widget Configuration:
In the Agent Desktop settings, ensure the Video Chat widget is added to the workspace layout. Configure the widget to auto-open on incoming video interactions.

  • Navigate to Admin > User Management > Desktop Layouts.
  • Edit the layout assigned to video-capable agents.
  • Add the Video Chat widget.
  • Set Auto Open to true for the Video Chat widget.

The Trap: Disabling Auto Open for the Video Chat widget.
Downstream Effect: The agent receives the interaction, but the video pane remains minimized or hidden. The agent must manually expand the widget to view the customer video. During this delay, the customer may perceive the agent as inactive. If the agent fails to expand the widget, the video stream may not initialize, causing a timeout. This creates a support burden where agents report “Video not working” when the issue is purely a workspace configuration.

Architectural Reasoning: The agent desktop operates on an event-driven model. When the contact media type changes to videoChat, the platform emits a media-upgrade event to the desktop. The workspace layout must subscribe to this event and trigger the widget expansion. Disabling Auto Open decouples the event from the UI action, requiring manual intervention. In high-volume environments, manual widget management introduces latency and increases the risk of dropped interactions.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Browser Autoplay and Permission Policies

Failure Condition: The video upgrade initiates, but the customer sees a black screen with no video feed. The agent also sees a black screen. Audio may work, or it may be silent.

Root Cause: Modern browsers enforce strict autoplay policies. If the customer has previously denied camera/microphone permissions, or if the browser blocks autoplay due to lack of user interaction, the WebRTC stream fails to initialize. Safari is particularly aggressive in blocking video streams that do not originate from a direct user gesture.

Solution: Ensure the video upgrade button in the SDK is triggered by a direct click event. The SDK must call getUserMedia within the click handler context. If using a custom SDK integration, verify that the click event propagates correctly to the video initialization function. Additionally, check the browser console for NotAllowedError or PermissionDeniedError. Instruct customers to grant permissions when prompted. For enterprise deployments, consider implementing a permission check prior to the flow trigger.

Edge Case 2: Session Analytics Gap During Upgrade

Failure Condition: The interaction transcript shows a gap or discontinuity between the web messaging portion and the video portion. Reporting shows two separate interactions or missing handle time.

Root Cause: The Contact ID variable is not correctly mapped across the Send Message and Video Chat blocks. If the flow creates a new contact ID during the video block, the platform treats the video session as a distinct interaction. This breaks the session continuity and fragments analytics.

Solution: Verify that the Contact ID input on the Video Chat block is mapped to the same variable used by the Web Messaging trigger. Do not use a default or empty value. In the flow JSON, ensure the contactId field references the existing contact variable. Validate this by checking the Interaction API response after the upgrade; the id field must remain constant throughout the transition.

Edge Case 3: STUN/TURN Traversal Failure in Corporate Networks

Failure Condition: Video upgrade works on public Wi-Fi but fails on corporate networks. The SDK logs indicate ICE candidate gathering failed or Connection timed out.

Root Cause: Corporate firewalls block UDP traffic required for WebRTC peer-to-peer signaling. Genesys Cloud uses STUN servers for NAT traversal, but some networks require TURN servers for relay. If the network blocks UDP, the WebRTC connection cannot establish.

Solution: Configure the Genesys Cloud Video Chat settings to enable TURN relay. In Admin > Video Chat Settings, ensure Use TURN Server is enabled. This forces the platform to route media through Genesys Cloud TURN servers, which use TCP fallback if UDP is blocked. Verify that the corporate firewall allows outbound HTTPS traffic to Genesys Cloud domains. Provide the customer with the required TURN configuration if they use a custom STUN/TURN provider.

Official References