Implementing ATM and Kiosk Remote Assistance Integration with Video-Enabled Contact Centers

How-To-Articles
1

Implementing ATM and Kiosk Remote Assistance Integration with Video-Enabled Contact Centers

What This Guide Covers

This guide details the architectural implementation of a bidirectional video and data integration between physical self-service kiosks (ATMs, ticketing machines, retail checkouts) and a Genesys Cloud CX contact center. You will configure the Genesys Cloud Video API to establish peer-to-peer WebRTC sessions, implement screen-sharing capabilities for remote troubleshooting, and inject contextual transaction data into the agent desktop via CTI events. The end result is a unified agent experience where a customer at a remote kiosk can initiate a video session, share their device screen, and allow an agent to view real-time transaction logs without requiring separate third-party middleware.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Genesys Cloud CX 1 or higher: Base licensing for voice and digital channels.
  • Video Add-on License: Required for both the agent (participant) and the kiosk endpoint (participant). Video calls consume concurrent session licenses.
  • Developer License: Required for the engineering team to access the Genesys Cloud Developer Portal and generate OAuth tokens for the kiosk SDK integration.

Permissions & Scopes

  • Admin Permissions: Telephony > Trunk > Edit, User Management > User > Edit, Architect > Flow > Edit.
  • OAuth Scopes: The kiosk application service account requires the following scopes:
    • video:read
    • video:write
    • telephony:user:call
    • telephony:call:control
    • data:read

External Dependencies

  • Kiosk Hardware: Devices must support WebRTC (Chrome-based OS, Windows 10/11 with Chrome/Edge, or custom embedded Linux with Chromium).
  • Network Infrastructure: Kiosk locations must have low-latency, jitter-free internet connections. UDP ports 10000-20000 must be open for WebRTC media streams.
  • Certificate Management: TLS 1.2+ certificates valid for the kiosk domain to ensure secure signaling.

The Implementation Deep-Dive

1. Architecting the Kiosk-to-Agent Handoff Flow

The core challenge in kiosk integration is not the video stream itself, but the context transfer. A standard video call lacks the telephony metadata (ANI, DNIS) that agents rely on. We must simulate a telephony call flow to leverage existing Genesys Cloud Architect routing logic.

Step 1.1: Define the Virtual Trunk and Route Pattern

We treat the kiosk application as an external SIP trunk. This allows us to use standard Architect IVR flows to route the request based on transaction type, location, or priority.

  1. Navigate to Admin > Telephony > Trunks.

  2. Create a new SIP Trunk. Name it Kiosk_Video_Trunk.

  3. In the Advanced Settings, ensure Media Region matches the region where the majority of your kiosks are located to minimize latency.

  4. Note the Trunk ID. You will need this for the API integration.

  5. Navigate to Admin > Telephony > Routes.

  6. Create a new Route Pattern.

    • Pattern: KIOSK_* (or a specific DID range if using telephony numbers).
    • Associated Trunk: Select Kiosk_Video_Trunk.
    • Associated Flow: Link this to a new Architect Flow named Kiosk_Video_Routing.

The Trap: Do not use a standard “Digital Engagement” (Chat/Video) flow for the initial handshake. Digital flows do not support the complex conditional routing required for high-volume kiosk traffic (e.g., routing based on transaction error codes embedded in the header). Using a Voice/Video Telephony flow allows you to parse headers and route intelligently before the session connects.

Step 1.2: Construct the Architect Flow

In the Kiosk_Video_Routing flow:

  1. Trigger: Set to Incoming Call.
  2. Set Variables:
    • Extract the X-Kiosk-Location header.
    • Extract the X-Transaction-ID header.
    • Set a variable Agent_Skill based on the transaction type (e.g., CashDispenserError, CardJam, GeneralInquiry).
  3. Queue Action:
    • Add a Queue block.
    • Select the queue dedicated to Kiosk Support.
    • Enable Video as an allowed channel.
    • Critical Configuration: In the Queue settings, ensure Video is checked under Allowed Channels. If this is unchecked, the call will fail to connect to agents with video licenses.
  4. Agent Assignment:
    • Use Skills-Based Routing. Assign the skill derived from the header.
    • Set Overflow to a secondary queue or voicemail if no video agents are available.

Architectural Reasoning: By routing through a Queue, we gain access to Genesys Cloud’s WFM (Workforce Management) integration. This ensures that only logged-in, scheduled agents with the Video license are offered the call. It also provides analytics on wait times and abandonment rates specific to kiosk failures.

2. Implementing the Kiosk Client SDK Integration

The kiosk does not use the Genesys Cloud Agent Desktop. It uses a custom application built on the Genesys Cloud Video API. This application runs in a locked-down browser or kiosk mode.

Step 2.1: Initialize the Video Client

The kiosk application must authenticate using a Service Account or a temporary User Token. For scalability, use a Service Account with the video:write scope.

// Pseudo-code for Kiosk Frontend SDK Initialization
const GenesysCloud = require('@genesyscloud/video-client-sdk');

async function initiateKioskSession(kioskId, transactionId) {
  // 1. Authenticate
  const token = await getOAuthToken(serviceAccountId, serviceAccountSecret);
  
  // 2. Initialize Video Client
  const videoClient = new GenesysCloud.VideoClient({
    token: token,
    region: 'us-east-1'
  });

  // 3. Create a Video Call
  // Note: We are creating a call to a specific DID or using the API to inject into a flow
  const callPayload = {
    "to": { "phoneNumber": "+15551234567" }, // The DID associated with the Kiosk Route Pattern
    "from": { "phoneNumber": "+15550000000" }, // Kiosk's virtual number
    "media": {
      "audio": true,
      "video": true,
      "screenShare": true
    },
    "headers": {
      "X-Kiosk-Location": kioskId,
      "X-Transaction-ID": transactionId,
      "X-Content-Type": "video/kiosk-support"
    }
  };

  try {
    const response = await videoClient.createCall(callPayload);
    return response.callId;
  } catch (error) {
    console.error("Failed to initiate video session", error);
    throw error;
  }
}

Step 2.2: Injecting Context via CTI Events

The video call alone does not push data to the agent’s screen pop. We must use the Telephony API to update the call context while the video session is active.

When the video session is established, the kiosk application should trigger an API call to update the call’s metadata. This metadata can then be displayed on the agent’s desktop using Custom Fields.

  1. Admin > User Management > Users > Custom Fields:

    • Create Custom Fields for the Call object:
      • kiosk_location_code (String)
      • transaction_id (String)
      • error_code (String)

  2. API Call from Kiosk Backend:
    Once the callId is returned from the video creation, the kiosk backend (Node.js/Python) must patch the call object.

    HTTP Method: PATCH
    Endpoint: https://api.us-east-1.genesyscloud.com/v2/telephony/providers/edge/calls/{callId}

    JSON Body:

    {
  "customData": {
    "kiosk_location_code": "NYC_AIRPORT_T1",
    "transaction_id": "TXN_99887766",
    "error_code": "E404_CARD_READ_FAIL"
  }
}

The Trap: Do not attempt to pass large JSON payloads (e.g., full transaction logs) in the SIP headers or call custom data. SIP headers have length limits (typically 4KB). Large payloads will cause the SIP INVITE to drop. Instead, pass a unique transaction_id and have the agent desktop fetch the full log from your internal CRM/Transaction Database using that ID via a separate REST API call.

3. Configuring the Agent Desktop Experience

The agent needs a unified view. They should see the video feed, the screen share from the kiosk, and the contextual data simultaneously.

Step 3.1: Enable Video in Agent Desktop

  1. Navigate to Admin > User Management > Users.
  2. Select the agent.
  3. Under Licenses, ensure Video is checked.
  4. Under Preferences, enable Video Calls.

Step 3.2: Customize the Call Control Widget

To display the kiosk-specific data, we use Genesys Cloud Engage or a custom Web Component if using the embedded agent desktop.

  1. Navigate to Admin > User Management > User Interface > Layouts.
  2. Select the Call Control widget.
  3. Add Custom Fields to the layout:
    • Drag kiosk_location_code to the header area.
    • Drag transaction_id to the details area.
  4. Screen Share Handling:
    • When the kiosk initiates screen sharing, Genesys Cloud automatically generates a second media stream.
    • In the Agent Desktop, this appears as a Screen Share tab within the video widget.
    • Configuration: Ensure the agent desktop is updated to the latest version to support dual-stream video (camera + screen). Older versions may only render one stream.

Architectural Reasoning: Using Custom Fields on the Call object ensures that the data is tied to the specific call instance. If you use User Custom Fields, the data persists after the call ends and may bleed into the next call. Call Custom Fields are ephemeral and tied to the conversation lifecycle, which is critical for data privacy (PCI-DSS/HIPAA).

4. Implementing Screen Sharing for Remote Troubleshooting

Screen sharing is the most valuable feature for kiosk support. It allows the agent to see exactly what the customer sees, including error messages and UI states.

Step 4.1: Kiosk Screen Share Initiation

The kiosk application must explicitly request screen share permissions. In a kiosk environment, the browser is locked, so we cannot rely on the standard browser prompt. We must use the getDisplayMedia API with pre-authorized permissions or a custom kiosk OS integration.

// Kiosk Frontend: Initiate Screen Share
async function startScreenShare(callId) {
  try {
    // Request screen access (may require kiosk OS configuration to auto-approve)
    const stream = await navigator.mediaDevices.getDisplayMedia({
      video: {
        cursor: "always",
        displaySurface: "monitor"
      }
    });

    // Add the screen share stream to the existing video call
    await videoClient.addTrack(callId, stream.getVideoTracks()[0], "screen");
    
    // Notify backend to update call status
    await updateCallStatus(callId, "SCREEN_SHARE_ACTIVE");
  } catch (err) {
    console.error("Screen share failed", err);
  }
}

Step 4.2: Agent Side Screen Share Reception

The agent does not need to do anything special to receive the screen share. It appears as a new tab in the video widget. However, we must ensure the agent has sufficient bandwidth.

Bandwidth Considerations:

  • Standard Video: 720p at 30fps (~1.5 Mbps).
  • Screen Share: 1080p at 15fps (~2 Mbps) due to high detail requirements for text readability.
  • Total Bandwidth per Agent: ~3.5 Mbps upload/download.

The Trap: If the kiosk location has poor upload bandwidth, the screen share will freeze or degrade to 144p. Implement a Quality of Service (QoS) policy on the kiosk network that prioritizes UDP traffic on ports 10000-20000. Additionally, configure the Genesys Cloud Video Client SDK on the kiosk to dynamically adjust bitrate based on network conditions.

// Kiosk SDK: Configure Adaptive Bitrate
videoClient.setVideoSettings({
  maxBitrate: 2000000, // 2 Mbps
  minBitrate: 500000,  // 500 kbps
  framerate: 15,       // 15 fps for screen share
  resolution: "1280x720"
});

Validation, Edge Cases & Troubleshooting

Edge Case 1: Screen Share Blackout on macOS/Windows Kiosks

The Failure Condition: The agent sees a black screen instead of the kiosk UI.
The Root Cause: Modern OSes (macOS Catalina+, Windows 10/11) block screen capture for security reasons unless the application is explicitly granted permission. In a kiosk mode, the user cannot interact with the permission dialog.
The Solution:

  • macOS: Use a dedicated kiosk application (Electron/Node) and add it to the “Screen Recording” permissions in System Preferences. You may need to use a helper app with elevated privileges to grant this automatically during deployment.
  • Windows: Use Group Policy Objects (GPO) to pre-approve screen capture for the kiosk browser executable.

Edge Case 2: Video Stream Latency and Audio Desync

The Failure Condition: The agent sees the kiosk screen 2-3 seconds after the audio plays, causing confusion during troubleshooting.
The Root Cause: WebRTC uses different codecs for audio (Opus) and video (VP8/VP9/H.264). If the network is congested, the video buffer grows larger than the audio buffer.
The Solution:

  • Enable Jitter Buffer Adjustment in the Genesys Cloud Video settings.
  • Set the Max Jitter Buffer to 200ms. This forces the browser to drop late packets rather than buffering them, reducing latency at the cost of minor quality artifacts.
  • Ensure the kiosk and agent are in the same Genesys Cloud Region. Cross-region video adds 50-100ms of latency inherently.

Edge Case 3: Custom Data Not Appearing on Agent Desktop

The Failure Condition: The PATCH call succeeds (200 OK), but the agent sees empty custom fields.
The Root Cause: The agent desktop caches call data. If the PATCH happens before the agent answers, the data might not be refreshed in the UI until the next poll interval (usually 5-10 seconds).
The Solution:

  • Implement a Webhook in Genesys Cloud for telephony.calls.updated.
  • When the webhook fires with the custom data, trigger a Screen Pop update in the agent desktop via the Genesys Cloud JavaScript SDK.
  • Alternatively, instruct agents to click the “Refresh” icon in the call control widget if data is missing.

Edge Case 4: Kiosk Reboots Mid-Session

The Failure Condition: The kiosk loses power or crashes during a video session.
The Root Cause: The WebRTC connection drops abruptly. The agent remains on the line, waiting for a reconnection that will not happen.
The Solution:

  • Implement a Heartbeat Mechanism in the kiosk application. If the heartbeat fails for 10 seconds, trigger a graceful disconnect.
  • In the Architect Flow, set a Call Timeout of 5 minutes. If the kiosk does not reconnect within this time, the flow should transfer the call to voicemail or a callback queue.
  • Use the Genesys Cloud Telephony API to detect call.disconnected events and automatically clean up custom data to prevent data leakage to the next call.

Official References