Troubleshooting WebRTC ICE Candidate Gathering Failures in Genesys Cloud Agent Desktop When Behind Symmetric NATs Requiring STUN/TURN Server Fallback Configuration

How-To-Articles
1

Troubleshooting WebRTC ICE Candidate Gathering Failures in Genesys Cloud Agent Desktop When Behind Symmetric NATs Requiring STUN/TURN Server Fallback Configuration

What This Guide Covers

This guide provides a systematic approach to diagnosing and resolving WebRTC ICE candidate gathering failures in the Genesys Cloud Agent Desktop caused by symmetric NAT topologies. You will configure STUN/TURN fallback mechanisms, validate network paths, and apply browser-level WebRTC constraints to guarantee stable media sessions under restrictive enterprise network conditions.

Prerequisites, Roles & Licensing

  • Licensing Tier: Genesys Cloud CX Standard or Premium (Voice feature required). WFM or Analytics add-ons are not required for this configuration.
  • Granular Permissions: Telephony > Network > View, Telephony > Network > Edit, System Admin > Platform > Edit, Telephony > Agent Desktop > View
  • OAuth Scopes: telephony:network:read, telephony:network:edit, admin:platform:read
  • External Dependencies: Enterprise firewall rules allowing UDP 10000-65535 and TCP/TLS 443 to Genesys Cloud STUN/TURN endpoints, browser with WebRTC support (Chrome 88+, Edge 88+, Firefox 78+), enterprise MDM or group policy deployment capability for browser constraints.

The Implementation Deep-Dive

1. Diagnose ICE Candidate Gathering Failures Using Browser DevTools and Genesys Cloud Logs

WebRTC relies on Interactive Connectivity Establishment (ICE) to negotiate media paths through NAT devices. In a symmetric NAT environment, the router assigns a unique public IP and port combination for each distinct destination. Standard STUN protocols cannot establish a consistent reflexive candidate because the port changes per peer. When Genesys Cloud Agent Desktop attempts to gather candidates, the ICE agent collects host candidates, attempts to query STUN for srflx candidates, and then fails to establish a stable path. The connection state transitions to disconnected or failed before media exchanges begin.

Open the browser developer console and navigate to chrome://webrtc-internals (or edge://webrtc-internals). Initiate a test call through the Agent Desktop. Monitor the IceCandidate events and the iceConnectionState lifecycle. A symmetric NAT failure presents a specific signature in the candidate gathering timeline:

  • host candidates are generated successfully.
  • srflx candidates appear but fail connectivity checks.
  • relay candidates are absent or appear after a prolonged timeout.
  • The state machine flips to failed within 4 to 6 seconds.

Execute the following console snippet to capture real-time ICE candidate generation and filter for relay attempts:

const origCreateOffer = RTCPeerConnection.prototype.createOffer;
RTCPeerConnection.prototype.createOffer = function() {
  return origCreateOffer.call(this).then(offer => {
    console.log('[ICE DIAG] SDP Offer generated. Checking iceTransportPolicy:', offer.sdp.match(/a=ice-options:(.*)/));
    return offer;
  });
};

window.addEventListener('icecandidate', (event) => {
  if (event.candidate) {
    console.log(`[ICE DIAG] Candidate type: ${event.candidate.type}, Foundation: ${event.candidate.foundation}, Protocol: ${event.candidate.protocol}`);
  } else {
    console.log('[ICE DIAG] ICE Gathering Complete');
  }
});

The Trap: Assuming UDP blockage when the actual issue is symmetric NAT port churn. Administrators frequently whitelist fixed UDP ranges (such as 10000-20000) based on legacy SIP trunk documentation. WebRTC does not use fixed port ranges. It requires dynamic UDP allocation. If the network device implements symmetric NAT, whitelisting static ranges provides zero benefit because the NAT table reassigns ephemeral ports for each new peer destination.

Architectural Reasoning: We diagnose at the browser level because Genesys Cloud Agent Desktop abstracts the underlying RTCConfiguration object. The platform handles ICE restart logic, but it cannot override enterprise network behavior. Identifying the exact candidate type that fails determines whether the solution requires STUN tuning, TURN enforcement, or firewall modification. Symmetric NATs inherently break STUN because the protocol assumes a one-to-one port mapping. Only a relay (TURN) provides a static public endpoint that survives symmetric port reassignment.

2. Configure STUN/TURN Fallback in Genesys Cloud Network Settings

Genesys Cloud provides a global TURN infrastructure, but enterprise deployments must explicitly associate network segments with TURN fallback policies. When ICE gathering stalls, the platform must know which TURN endpoints to query for relay allocation. Misconfigured network objects cause the Agent Desktop to fall back to TCP signaling while media attempts to route over UDP, resulting in one-way audio or complete media blackouts.

Access the Admin console and navigate to Telephony > Networks. Create or edit the network object corresponding to your agent subnet. Within the network configuration, locate the WebRTC/TURN settings. You must define explicit TURN servers with transport protocol preferences. The platform accepts TURN URIs with transport modifiers to dictate fallback order.

Configure the network via the Admin UI or via the REST API. The API approach provides version control and audit trails for infrastructure changes. Use the following endpoint and payload:

HTTP Method: PUT
Endpoint: /api/v2/telephony/networks/{networkId}
OAuth Scopes: telephony:network:edit

{
  "name": "Enterprise-Agent-Subnet-10.20.0.0/16",
  "ipAddressRanges": [
    "10.20.0.0/16"
  ],
  "webrtc": {
    "useTurnServers": true,
    "turnServers": [
      {
        "uri": "turn:turn1.pure.cloud:3478?transport=udp",
        "username": "genagent",
        "credential": "TURN_ALLOC_CREDENTIAL_PLACEHOLDER"
      },
      {
        "uri": "turn:turn1.pure.cloud:443?transport=tcp",
        "username": "genagent",
        "credential": "TURN_ALLOC_CREDENTIAL_PLACEHOLDER"
      },
      {
        "uri": "turns:turns1.pure.cloud:443?transport=tls",
        "username": "genagent",
        "credential": "TURN_ALLOC_CREDENTIAL_PLACEHOLDER"
      }
    ],
    "iceTransportPolicy": "relay"
  },
  "stunServers": [
    "stun:stun.pure.cloud:3478"
  ]
}

The Trap: Configuring TURN servers but leaving iceTransportPolicy set to all. When the policy is all, the browser attempts host connectivity, then STUN reflexive checks, and finally falls back to relay. Under symmetric NAT, STUN checks fail and consume the ICE gathering timeout window (typically 5 seconds). By the time the ICE agent initiates the TURN allocation request, the peer connection state has already transitioned to failed, and the Agent Desktop displays a network error.

Architectural Reasoning: We set iceTransportPolicy: "relay" at the network level to force the ICE agent to skip STUN discovery and immediately request a TURN allocation. This eliminates negotiation latency and guarantees that the media path traverses a stable relay endpoint. The triple-URI configuration (UDP, TCP, TLS) provides transport resilience. If the enterprise firewall blocks UDP, the ICE agent falls back to TCP 443, then TLS 443. TURN over TLS is the most reliable path in zero-trust architectures because it piggybacks on standard HTTPS egress rules.

3. Enforce TURN-Only Media Path via WebRTC Constraints and Browser Policies

Genesys Cloud Agent Desktop respects platform network settings, but browser-level WebRTC implementations maintain independent policy engines. Enterprise browsers often enforce security restrictions that override platform configurations. Chrome and Edge maintain WebRTC settings in their internal policy registry. Firefox uses about:config preferences. Without explicit policy enforcement, browser updates or group policy refreshes can revert ICE behavior to default, causing intermittent media failures.

Deploy the following JSON configuration via your enterprise MDM or Group Policy Object (GPO) to enforce TURN preference and disable problematic WebRTC features:

{
  "WebRtcForceTurn": true,
  "WebRtcUseMdns": false,
  "WebRtcAllowTcp": true,
  "WebRtcAllowTls": true,
  "WebRtcEnableNetworkIgnoreMask": false,
  "WebRtcUseLoopback": false
}

Map this policy to the Chrome/Edge enterprise policy registry:

  • Windows Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome
  • macOS Configuration Profile: com.google.Chrome payload
  • Linux: /etc/chrome/policies/managed/webrtc_policy.json

For Firefox deployments, configure the following about:config preferences via group policy or enterprise extension:

  • media.peerconnection.ice.relay_only = true
  • media.peerconnection.ice.no_host = true
  • media.peerconnection.turn.disable = false

The Trap: Enforcing TURN without verifying UDP connectivity to the TURN server. TURN can operate over UDP, TCP, or TLS. If the enterprise firewall only allows TCP outbound traffic, but the browser policy defaults to UDP TURN attempts, the relay handshake fails. The ICE agent logs turn: allocation request failed and the peer connection drops.

Architectural Reasoning: We enforce WebRtcForceTurn: true at the browser level to guarantee that the platform network configuration is respected regardless of browser version or user profile state. Disabling mDNS (WebRtcUseMdns: false) prevents the browser from attempting local network discovery, which fails in segmented enterprise VLANs and adds unnecessary latency to the ICE gathering timeline. Enabling TCP and TLS TURN options ensures graceful degradation when UDP is restricted by middleboxes or deep packet inspection appliances.

4. Validate Media Flow and Implement Continuous Monitoring

Configuration enforcement requires validation against live media sessions. Initial ICE success does not guarantee long-term stability. Symmetric NAT devices and enterprise firewalls often allow initial handshake packets but drop UDP keepalives or enforce strict idle timeouts. You must verify that relay candidates remain active throughout the call lifecycle and that packet loss metrics stay within acceptable thresholds.

Navigate to chrome://webrtc-internals and initiate a 5-minute test call. Monitor the following metrics in the statistics graph:

  • googCurrentRoundTripTimeMs: Should remain stable between 15ms and 80ms. Spikes indicate TURN allocation instability.
  • packetsLost and packetsSent: Loss ratio must remain below 0.5%. Higher values indicate middlebox interference or TURN server congestion.
  • googActiveConnection: Must show true with a selectedCandidatePairId referencing a relay candidate.

Extract the active candidate pair using the following console command during the call:

const pc = window.RTCPeerConnection ? new RTCPeerConnection() : null;
// Note: In production, inject into existing Agent Desktop peer connection via shadow DOM or browser extension
// For validation, use webrtc-internals statistics export
const stats = await pc.getStats();
stats.forEach(report => {
  if (report.type === 'candidate-pair' && report.state === 'succeeded') {
    console.log(`[VALIDATION] Active pair: ${report.id}, Nominated: ${report.nominated}, Type: ${report.remoteCandidateType}`);
  }
});

Configure Genesys Cloud Analytics to monitor network quality at scale. Navigate to Analytics > Voice > Network Quality. Create a dashboard widget filtering by networkName and agentDesktopVersion. Track iceRestartCount and turnAllocationFailureRate. These metrics reveal infrastructure-level patterns that browser-level diagnostics cannot capture.

The Trap: Validating only initial call setup. Symmetric NATs sometimes allow the initial TURN allocation to succeed but drop UDP keepalives after 30 to 60 seconds of inactivity. This causes media to freeze while signaling remains active. Agents experience one-way audio or complete silence without call drop events.

Architectural Reasoning: We monitor continuous metrics because WebRTC maintains media paths through periodic STUN keepalives or TURN refresh messages. Enterprise stateful firewalls and symmetric NATs track UDP flows independently. If keepalives are blocked or throttled, the NAT entry expires, and subsequent media packets are dropped. TCP/TLS TURN maintains connection state through TCP keepalives, which are more resilient to NAT timeout policies. Validating long-term stability requires observing metrics beyond the initial 10-second handshake window.

Validation, Edge Cases & Troubleshooting

Edge Case 1: UDP Port Exhaustion on Symmetric NAT Devices

  • The failure condition: ICE gathering stalls indefinitely. Browser console logs ICE gathering failed after 15 seconds. Agent Desktop displays a generic network error without specific WebRTC diagnostics.
  • The root cause: Symmetric NATs allocate a new public port for each unique destination. High agent concurrency combined with multiple WebRTC media streams (audio, video, screen share) exhausts the NAT device port pool. The router cannot assign new ports, and ICE candidate generation blocks.
  • The solution: Coordinate with the network infrastructure team to increase the NAT port pool range or implement connection tracking optimizations. Reduce simultaneous WebRTC sessions per agent by disabling video/screen share when not required. Configure TURN allocation timeouts to 30 seconds to prevent indefinite blocking. Monitor NAT table utilization via router CLI commands such as show ip nat translations (Cisco) or pfctl -s nat (pfSense).

Edge Case 2: TURN TLS Certificate Pinning Failures on Legacy Browsers

  • The failure condition: RTCPeerConnection throws SecurityError during TURN handshake. Console displays Failed to create TURN transport: SSL handshake failed. Media never initiates.
  • The root cause: Older browser versions or strict enterprise proxy inspection strips or replaces TURN TLS certificates. Genesys Cloud TURN servers present certificates signed by trusted CAs, but transparent SSL inspection appliances inject their own root certificates. Browsers that do not trust the inspection root reject the TURN allocation.
  • The solution: Update browsers to current enterprise-supported versions. Configure the proxy to bypass Genesys Cloud TURN endpoints (*.pure.cloud, *.genecys.com). If bypass is unavailable, enforce TCP 443 TURN with transport-protocol:tcp in the network configuration, as TCP TURN often tolerates certificate mismatches better than TLS TURN in restrictive inspection environments.

Edge Case 3: WebRTC Worker Context Isolation in Enterprise Browsers

  • The failure condition: ICE candidates gather successfully, but media never flows. Console shows Permission denied to access property 'RTCSessionDescription' from cross-origin context.
  • The root cause: Browser security policies (CSP, SameSite cookies, cross-origin isolation) block WebRTC worker communication. Genesys Cloud Agent Desktop runs media processing in web workers for performance. Strict enterprise CSP headers or third-party cookie blocking prevent the worker from posting ICE candidates to the main thread.
  • The solution: Ensure Genesys Cloud domains (*.mypurecloud.com, *.genecys.com) are added to browser trusted sites. Disable aggressive third-party cookie blocking for Genesys Cloud origins. Verify crossOrigin isolation headers if deploying custom Agent Desktop wrappers. Clear browser cache and hard refresh the Agent Desktop to reload worker scripts under the updated policy context.

Official References