Implementing One-Way Video Escalation from Web Chat for Visual Product Troubleshooting

How-To-Articles
1

Implementing One-Way Video Escalation from Web Chat for Visual Product Troubleshooting

What This Guide Covers

This guide details the architectural implementation of a one-way video escalation channel within a Genesys Cloud CX engagement. You will configure a Web Chat interaction that allows an agent to request and view a live video stream from a customer’s mobile device without establishing a bidirectional video connection. The end result is a seamless transition from text-based troubleshooting to visual inspection, where the agent receives a WebRTC stream while the customer retains control of their camera and audio, minimizing bandwidth usage and reducing customer friction.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Genesys Cloud CX License: CX 1, CX 2, or CX 3. Video capability is included in all CX tiers, but high-concurrency video streams may impact your concurrent session limits.
  • Web Chat License: Enabled on the account.
  • Video Messaging or Live Video Add-on: Depending on your specific region and contract, ensure the “Live Video” feature flag is active. Standard Web Chat does not include video by default; it requires the Video capability to be provisioned.

Permissions & Roles

  • Architect: Telephony > Video > Edit and Engagement > Chat > Edit.
  • Administrator: Telephony > Trunk > Edit (if using custom STUN/TURN servers) and Security > OAuth Client > Edit (for custom Web Chat embeds).
  • Agent Role: Must have the Video > Answer and Video > Hold permissions. The agent role must also include Chat > Answer to handle the initial text interaction.

Technical Dependencies

  • WebRTC Support: Customer browsers must support WebRTC. Safari on iOS requires specific getUserMedia constraints.
  • STUN/TURN Servers: Genesys Cloud provides default STUN servers. For enterprise deployments behind strict NATs, you may need to configure custom TURN servers.
  • Custom Web Chat Embed: You cannot use the standard out-of-the-box Web Chat widget for this specific one-way workflow without significant customization. You will use the Genesys Cloud Web Chat SDK or a custom React/Angular implementation using the genesys-cloud-webchat package.

The Implementation Deep-Dive

1. Configuring the Video Capability in Architect

The foundation of this workflow is the correct configuration of the Video capability within the Genesys Cloud engagement. Unlike standard bidirectional video, one-way video relies on the agent receiving a stream while the customer transmits. This asymmetry requires specific handling in the Architect flow to ensure the media pipeline is established correctly.

Step 1.1: Enable Video in the IVR Flow

In your Architect flow, you must initiate the video capability before routing the interaction to a queue.

  1. Open Architect and create a new flow or edit an existing Web Chat flow.
  2. Add a Start Video block.
  3. Configure the block:
    • Mode: Select One-Way. This is critical. If you select Two-Way, the system will attempt to establish a bidirectional stream, requiring the agent to transmit video as well, which increases bandwidth and complexity.
    • Video Source: Set to Camera.
    • Audio Source: Set to Microphone (optional, depending on if you want audio along with video).
  4. Connect the Success output to a Queue block.

The Trap: Configuring the Start Video block with Two-Way mode for a visual troubleshooting scenario.
The Downstream Effect: When the agent answers, the system expects the agent to send video. If the agent does not have a camera enabled or chooses not to share video, the media pipeline may hang, or the customer may see a black screen expecting to see the agent. More critically, Two-Way mode consumes significantly more bandwidth on both ends. For product troubleshooting, the agent only needs to see the product. One-Way mode ensures the media path is optimized for inbound video only, reducing latency and jitter.

Step 1.2: Queue Configuration for Video-Enabled Agents

The queue must be configured to handle video interactions.

  1. Navigate to Admin > Routing > Queues.
  2. Select the queue used in the Architect flow.
  3. In the Skills tab, ensure the skill associated with video troubleshooting is added.
  4. In the Outbound tab (if applicable), ensure video is enabled. However, for inbound Web Chat escalation, the critical setting is in the Queue Settings:
    • Ensure Video is checked under Supported Channels.
  5. Agent Skill Requirements: Agents must have the specific skill assigned to their user profile to be routed to this queue.

The Trap: Routing video interactions to a queue that does not have the Video channel enabled.
The Downstream Effect: The interaction will fail to connect to an agent. The customer will remain in the queue indefinitely, or the interaction will drop with a generic “No agents available” error, even if agents are online. The system silently filters out agents who cannot handle the video channel.

2. Building the Custom Web Chat Embed

The standard Genesys Cloud Web Chat widget does not expose the necessary controls for one-way video escalation out of the box. You must build a custom embed using the Genesys Cloud Web Chat SDK. This allows you to intercept the video request and manage the WebRTC peer connection.

Step 2.1: Initialize the Web Chat SDK

Use the genesys-cloud-webchat package in your React application.

import { ChatProvider, useChat } from '@genesys/webchat';

function App() {
  const { startChat, sendText, startVideo } = useChat();

  const handleVideoEscalation = async () => {
    try {
      // Request camera access from the customer's device
      const stream = await navigator.mediaDevices.getUserMedia({
        video: { width: { ideal: 1280 }, height: { ideal: 720 } },
        audio: true
      });

      // Send the video stream to Genesys Cloud
      await startVideo({
        stream: stream,
        direction: 'one-way' // Explicitly set one-way direction
      });

      console.log('Video stream started successfully');
    } catch (error) {
      console.error('Failed to start video:', error);
    }
  };

  return (
    <div>
      <button onClick={handleVideoEscalation}>Start Video Escalation</button>
    </div>
  );
}

The Trap: Not handling the getUserMedia permission prompt gracefully.
The Downstream Effect: If the customer denies camera access, the startVideo call will fail. Without proper error handling, the UI will freeze or throw an unhandled promise rejection, breaking the chat experience. You must catch the NotAllowedError and inform the user that camera access is required for video troubleshooting.

Step 2.2: Managing the Video Stream Lifecycle

You must manage the lifecycle of the video stream to ensure it stops when the agent ends the interaction.

useEffect(() => {
  const handleVideoEnd = () => {
    // Stop the camera stream when the agent ends the video
    stream.getTracks().forEach(track => track.stop());
  };

  // Subscribe to video end event
  chat.on('videoEnd', handleVideoEnd);

  return () => {
    chat.off('videoEnd', handleVideoEnd);
  };
}, []);

The Trap: Forgetting to stop the media tracks when the interaction ends.
The Downstream Effect: The camera light on the customer’s device will remain on, indicating an active stream. This causes privacy concerns and can lead to battery drain. The customer may perceive this as a security breach. Always explicitly stop all tracks in the cleanup function.

3. Agent Desktop Configuration

The agent experience is managed through the Genesys Cloud Agent Desktop. No custom code is required for the agent side, but configuration is critical.

Step 3.1: Agent Video Settings

Agents must ensure their video settings are configured correctly.

  1. Navigate to Admin > Users > [Agent Name].
  2. In the Video tab, ensure Video Enabled is checked.
  3. Set the Default Camera and Default Microphone.
  4. In the Agent Desktop, agents should see a video preview when they answer a video-enabled interaction.

The Trap: Agents using low-quality cameras or poor lighting.
The Downstream Effect: While this is not a configuration error, it impacts the efficacy of the troubleshooting. If the video quality is poor, the agent cannot identify the product issue. Provide agents with guidelines for lighting and camera positioning.

Step 3.2: Handling the One-Way Stream

When the agent answers the interaction, they will see the customer’s video stream. The agent does not need to enable their own camera.

  1. Answer the interaction in the Agent Desktop.
  2. The customer’s video will appear in the video pane.
  3. Use the Chat pane to send text instructions.
  4. Use the Hold button to pause the video stream if the agent needs to consult documentation.

The Trap: Agents attempting to share their own screen instead of using video.
The Downstream Effect: Screen sharing is a different media channel. It does not replace the need for the customer to show the physical product. Ensure agents understand that screen sharing is for showing diagrams, while video is for showing the physical product.

Validation, Edge Cases & Troubleshooting

Edge Case 1: NAT Traversal Failure

The Failure Condition: The customer initiates the video, but the agent sees a black screen. The chat connection remains active.

The Root Cause: The customer is behind a strict NAT or firewall that blocks WebRTC traffic. The default STUN servers cannot establish a direct peer-to-peer connection.

The Solution:

  1. Configure custom TURN servers in Genesys Cloud.
  2. Navigate to Admin > Telephony > Trunks > Video Trunks.
  3. Add a TURN server with authentication credentials.
  4. Update the Web Chat SDK configuration to include the TURN server credentials.
const config = {
  organizationId: 'YOUR_ORG_ID',
  region: 'US',
  turnServers: [
    {
      urls: 'turn:your-turn-server.com:443?transport=tcp',
      username: 'username',
      credential: 'password'
    }
  ]
};

Edge Case 2: iOS Camera Permission Delay

The Failure Condition: On iOS devices, the camera permission prompt appears, but the video stream does not start immediately after the user grants permission.

The Root Cause: iOS Safari requires the getUserMedia call to be triggered by a direct user gesture (e.g., a button click). If the call is made asynchronously or after a delay, the browser may block it.

The Solution:

  1. Ensure the startVideo function is called directly within the onClick handler of a button.
  2. Do not use setTimeout or other asynchronous delays before calling getUserMedia.
// Correct Implementation
const handleVideoEscalation = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  await startVideo({ stream });
};

// Incorrect Implementation
const handleVideoEscalation = async () => {
  setTimeout(async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    await startVideo({ stream });
  }, 1000);
};

Edge Case 3: Agent Video Quality Degradation

The Failure Condition: The agent experiences choppy video or low resolution.

The Root Cause: The customer’s device is sending video at a higher bitrate than the agent’s network can handle, or the Genesys Cloud media servers are congested.

The Solution:

  1. Limit the video resolution in the getUserMedia constraints.
  2. Use the ideal property to suggest a lower resolution.
const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: { ideal: 640 }, height: { ideal: 480 } }
});

Official References