Configuring CXone Video Interactions for Remote Patient Monitoring

How-To-Articles
1

Configuring CXone Video Interactions for Remote Patient Monitoring

What This Guide Covers

This guide details the end-to-end configuration of a HIPAA-compliant video consultation pipeline within NICE CXone, connecting remote patients to clinical agents via secure WebRTC sessions. You will implement TURN-based media routing, Studio-driven capacity-aware queuing, asynchronous patient context injection, and immutable recording policies. The completed deployment provides a production-ready video interaction channel with guaranteed media path stability, strict data residency, and full clinical auditability.

Prerequisites, Roles & Licensing

  • Licensing Tier: CXone Video Add-on, HIPAA/BAA Enterprise Tier, CXone Studio, WEM (if session recording and quality assurance are required)
  • IAM Permissions: Video > Video Queue > Edit, Video > Video Agent > Edit, Studio > Flow > Edit, Telephony > Network > View, Administration > User > Edit
  • OAuth Scopes: video:session:read, video:session:write, flow:execution:read, flow:execution:write, user:read
  • External Dependencies: Corporate STUN/TURN relay infrastructure or CXone-managed relay, EHR/CRM middleware (HL7 FHIR or REST), patient scheduling engine, KMS for recording encryption

The Implementation Deep-Dive

1. Media Path Architecture and TURN Relay Configuration

Healthcare networks enforce strict NAT traversal policies, aggressive firewall rules, and carrier-grade NAT on mobile networks. Direct peer-to-peer WebRTC connections fail under these conditions because ICE candidates cannot negotiate symmetric UDP ports. We force all clinical video sessions through a TURN relay to guarantee media path consistency, enable centralized recording, and maintain HIPAA audit trails.

Configure the network topology in CXone by defining custom STUN/TURN endpoints. Navigate to Telephony > Network > Video Network Settings. You will override the default public STUN servers with your enterprise relay infrastructure. The configuration requires explicit transport protocol selection. We mandate UDP for primary media transport and TCP for fallback when UDP is blocked by restrictive hospital firewalls.

The Trap: Leaving the default public STUN servers active while enabling TURN fallback. Public STUN servers do not sign BAAs, expose patient media metadata to third-party infrastructure, and cause ICE negotiation timeouts when healthcare proxies block untrusted TURN candidates. This misconfiguration triggers media handshake failures that appear as silent drops on the patient client.

Set the TURN relay policy to Force Relay. This disables hole-punching attempts and routes all RTP/RTCP streams through your authenticated relay. We use this approach because clinical video requires deterministic latency and centralized media capture for WEM integration. P2P optimization saves bandwidth but destroys compliance visibility.

PUT /api/v2/video/network-settings
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "stunServers": [
    "stun.your-hospital-domain.com:3478"
  ],
  "turnServers": [
    {
      "uri": "turn.relay.your-hospital-domain.com:443",
      "username": "cxone-clinical-relay",
      "credential": "AES256_HMAC_KEY",
      "transport": "udp"
    },
    {
      "uri": "turn.relay.your-hospital-domain.com:443",
      "username": "cxone-clinical-relay",
      "credential": "AES256_HMAC_KEY",
      "transport": "tcp"
    }
  ],
  "relayPolicy": "force",
  "encryptionRequired": true,
  "dataResidencyRegion": "US-EAST-1"
}

The encryptionRequired flag enforces SRTP for media and TLS 1.2+ for signaling. We enable dataResidencyRegion to guarantee that video packets and metadata never leave the approved geographic boundary. This setting directly satisfies HIPAA 164.312(e)(1) transmission security requirements.

2. Studio-Based Video Queue and Routing Logic

Video interactions consume significantly more compute and bandwidth per agent than voice. Standard telephony queue routing logic will overload agent desktops and degrade clinical throughput. We implement capacity-aware routing using CXone Studio with explicit concurrency limits and skill-based clinical routing.

Create a dedicated video queue in Administration > Queues > Video Queues. Set the queue mode to Longest Idle Agent with a maximum concurrent session cap per agent. Clinical agents typically handle one video consultation at a time. We set the queue capacity to match the licensed video agent count and enable Overflow to Voice for triage scenarios where video bandwidth is constrained on the patient side.

Build the Studio flow using the Video Queue element. Configure the routing strategy to evaluate clinical skills (e.g., cardiology, primary-care, telehealth-certified) before falling back to general availability. We attach a Wait Time Threshold of 120 seconds. If the patient remains in queue beyond this threshold, the flow triggers a Transfer to Voice action with a pre-recorded consent prompt. This prevents patient abandonment and maintains clinical workflow continuity.

The Trap: Using standard telephony queue capacity settings for video routing. Telephony queues assume agents can handle multiple concurrent calls via barge, whisper, or split-screen. Video agents cannot safely manage concurrent clinical sessions due to HIPAA context switching risks and desktop rendering limits. Misconfiguring this causes agent desktop crashes, session overlap, and compliance violations during concurrent video handoffs.

Set the Max Concurrent Sessions Per Agent to 1 at the queue level. This forces Studio to respect clinical isolation requirements. We also enable Agent Availability Rules to exclude agents in After-Call Work or Meeting states from video distribution. The Studio flow evaluates agent state before routing, preventing forced video invitations to unavailable clinicians.

POST /api/v2/video/queues
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "name": "RPM_Clinical_Video_Queue",
  "description": "Remote Patient Monitoring Video Routing",
  "queueType": "video",
  "routingStrategy": "longest_idle",
  "maxConcurrentSessionsPerAgent": 1,
  "overflowBehavior": "transfer_to_voice",
  "overflowQueueId": "voice-triage-queue-id",
  "waitTimeThresholdSeconds": 120,
  "skillRequirements": [
    {
      "skillName": "telehealth-certified",
      "skillLevel": 1,
      "required": true
    }
  ],
  "availabilityFilter": {
    "excludeStates": ["after_call_work", "meeting", "unavailable"]
  }
}

The overflowBehavior parameter ensures degraded bandwidth scenarios do not block clinical intake. We route to voice only after explicit patient consent, maintaining HIPAA transparency requirements.

3. Asynchronous Patient Context Injection via REST

Clinical video sessions require immediate patient context: demographic data, consent status, recent vitals, and scheduled appointment metadata. Blocking the Studio flow on synchronous EHR calls destroys WebRTC session establishment windows. ICE negotiation and media handshake completion typically require 8 to 12 seconds. A synchronous API call that exceeds this window causes the video session to terminate before the agent desktop renders.

We resolve this by injecting context asynchronously using CXone Webhooks and the Video Session API. The Studio flow triggers a Webhook element immediately after queue entry. The webhook posts to your middleware, which queries the EHR and returns context via the CXone Session Context API. The agent desktop receives the data via real-time attribute updates without blocking the media path.

The Trap: Placing a synchronous API Call element directly in the Studio flow before the Video Queue element. This blocks the WebRTC handshake thread, exceeds the 15-second Studio execution timeout, and drops the patient connection. The failure manifests as a generic “Session Ended” error on the patient client with no media ever established.

Configure the webhook to return within 3 seconds. We use a fire-and-forget pattern for non-critical context and a synchronous pattern only for consent validation. The consent status must block routing. We validate consent via a fast local cache before queue entry. All other clinical data flows asynchronously.

POST /api/v2/video/sessions/{sessionId}/context
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "customAttributes": {
    "patient_id": "MRN-8842910",
    "consent_status": "verified",
    "appointment_type": "rpm_follow_up",
    "vitals_last_read": "2024-05-12T14:30:00Z",
    "clinical_priority": "standard",
    "ehr_record_url": "https://ehr.hospital.local/fhir/Patient/8842910"
  },
  "metadata": {
    "source_channel": "patient_portal",
    "session_purpose": "remote_monitoring_review"
  }
}

The customAttributes object maps directly to the agent desktop context panel. We enforce strict schema validation on the middleware side. Invalid payloads are rejected before reaching CXone, preventing attribute pollution. The metadata object routes to WEM for session tagging and quality assurance classification.

4. HIPAA-Compliant Recording and Data Residency Policies

Clinical video interactions require immutable recording, access logging, and retention locks. Default CXone recording storage does not meet HIPAA audit requirements. We configure WEM integration with KMS encryption, retention policies, and access controls to satisfy 45 CFR 164.312.

Enable video recording at the queue level. Navigate to Video > Queues > RPM_Clinical_Video_Queue > Recording Settings. Set Recording Mode to Always and enable Secure Storage. This routes media files to the HIPAA-designated storage bucket with server-side encryption. We attach a retention policy of 7_years to comply with clinical record retention mandates.

The Trap: Storing video recordings on standard CXone storage without KMS key rotation or retention locks. This configuration fails HIPAA audits because recordings lack immutable access logs, allow unauthorized deletion, and do not enforce geographic data boundaries. Compliance officers will flag this during BAA review.

Configure the WEM recording policy to enforce Access Logging and Key Rotation. We map recording files to patient MRNs via the session context attributes injected in Step 3. This enables clinical staff to retrieve recordings through the EHR patient record interface rather than navigating CXone directly. The integration reduces audit surface area and maintains clinical workflow continuity.

PUT /api/v2/wem/recording-policies
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "name": "HIPAA_Video_Retention_Policy",
  "channel": "video",
  "storageType": "secure_encrypted",
  "encryptionKeyId": "arn:aws:kms:us-east-1:123456789012:key/clinical-video-kms",
  "retentionPeriodDays": 2555,
  "immutable": true,
  "accessLogging": true,
  "dataResidencyRegion": "US-EAST-1",
  "autoTagging": {
    "enabled": true,
    "tagSource": "customAttributes.patient_id",
    "tagPrefix": "RPM_REC_"
  }
}

The immutable flag prevents deletion or modification until the retention period expires. We enable autoTagging to link recordings to patient records automatically. This configuration satisfies HIPAA 164.312(a)(2)(iv) audit control requirements and 164.312(e)(1) transmission security mandates.

Validation, Edge Cases & Troubleshooting

Edge Case 1: STUN Discovery Failure Behind Carrier-Grade NAT

  • The failure condition: Patient clients report “Connecting…” indefinitely. Agent desktop never receives the video invitation. Network traces show ICE candidates failing to validate.
  • The root cause: Mobile carriers and enterprise healthcare proxies strip STUN binding requests or rewrite NAT mappings. The default STUN server cannot resolve public IP mappings, causing ICE negotiation to stall. WebRTC session establishment aborts after the 15-second timeout.
  • The solution: Force TURN relay mode and disable STUN fallback. Update the network settings to use only authenticated TURN endpoints with TCP fallback. Enable relayPolicy: force to bypass hole-punching entirely. Validate connectivity using turnutils_uclient from the patient network segment. If TURN connections fail, open UDP 3478-3481 and TCP 443/4443 to your relay infrastructure.

Edge Case 2: Concurrent Session Cap Exceeding Agent Desktop Render Limits

  • The failure condition: Agent desktop freezes or crashes when a second video session routes to the same agent. The first session drops audio/video tracks. Studio logs show AgentCapacityExceeded warnings.
  • The root cause: The video queue concurrency setting was left at the default 2 or higher. Clinical agents cannot safely render multiple active video streams due to GPU memory constraints and HIPAA context isolation requirements. The desktop attempts to initialize a second WebRTC peer connection, exhausting browser tab resources.
  • The solution: Set maxConcurrentSessionsPerAgent to 1 at the queue level. Enable Agent Availability Rules to exclude agents in active_video_session state from routing. Configure Studio to reject overflow sessions gracefully instead of forcing agent assignment. Monitor agent desktop performance via CXone Analytics > Video > Agent Concurrency Metrics. If desktop crashes persist, update the CXone Connect browser configuration to enable hardware acceleration limits and disable background tab rendering.

Edge Case 3: Asynchronous Context Injection Timing Out

  • The failure condition: Agent desktop shows empty context panel during the video call. Clinical staff must manually search the EHR. WEM recordings lack patient MRN tags.
  • The root cause: The middleware webhook exceeds the 3-second response window. CXone drops the context payload to preserve the media handshake. The customAttributes object arrives after the session state transitions to active, preventing UI rendering.
  • The solution: Implement a local consent cache for blocking validation. Route non-critical vitals and demographic data through a separate async pipeline that updates the session via the Context API after handshake completion. Add retry logic with exponential backoff to the webhook. Monitor webhook latency via CXone Studio > Flow Analytics > Webhook Performance. If latency exceeds 500ms consistently, move context retrieval to a pre-session polling job triggered by the patient portal login event.

Official References