Deploying 3CX WebRTC Gateway for Browser-Based Voice and Video Communications

Overview

Key takeaways

• Understand the underlying 3CX WebRTC architecture bridging WSS/SIP and DTLS-SRTP/RTP.
• Configure mandatory network ports, FQDNs, and trusted TLS certificates for browser security.
• Implement STUN and TURN server profiles to resolve symmetrical NAT media blocking.
• Enforce extension-level WebRTC rights for the 3CX Web Client and 3CX Live Chat.
• Troubleshoot common browser media issues including one-way audio and WebSockets handshake failures.

Prerequisites

• 3CX Phone System installed (v18 or v20 Enterprise or Professional license).
• Fully Qualified Domain Name (FQDN) with a valid, publicly trusted SSL/TLS certificate.
• Administrative access to perimeter firewalls and local network routers.
• Fundamental understanding of SIP, WebSockets, WebRTC, and DTLS-SRTP media flows.

Guide

1. section #1

   3CX WebRTC Gateway Architecture Overview

   WebSockets and SIP Translation

   3CX integrates WebRTC natively into its core architecture by deploying an internal gateway function. The gateway acts as a bridge, translating WebSockets Secure (WSS) frames sent from browser clients into standard SIP signaling messages for the 3CX SIP server.

   Media Protocols and Codec Negotiation

   For media delivery, browser clients cannot send standard unencrypted RTP. The 3CX WebRTC gateway enforces encryption using DTLS-SRTP for secure key exchange and payload protection. During session setup, the gateway dynamically negotiates modern media codecs.

   Supported WebRTC media capabilities:

   • Opus Codec: Delivers high-definition dynamic audio adapted to variable network bandwidth.
   • G.711 (PCMU/PCMA): Ensures legacy compatibility for PSTN bridging.
   • VP8 and H.264: Powers high-resolution video streams for WebRTC video calling and 3CX Meet.
2. section #2

   Network Protocols, Ports, and Certificate Requirements

   Web Security Context and FQDNs

   Modern web browsers restrict media capture device access (microphone and camera) exclusively to secure contexts (HTTPS). You must ensure your 3CX system operates using a valid domain name backed by a trusted Certificate Authority (CA) such as Let's Encrypt or a custom wildcard certificate.

   Firewall Port Forwarding Rules

   Proper firewall rules are necessary to maintain persistent WSS signaling and uninterrupted UDP media streams between remote web browsers and the 3CX PBX server.

   Essential port rules for WebRTC operations:

   • HTTPS/WSS Signaling: Forward TCP port 5001 (or 443) to the 3CX PBX.
   • Audio/Video Media Streams: Forward UDP ports 9000-10999 to allow RTP/SRTP payload transport.
   • STUN/TURN Resolution: Allow outbound UDP ports 3478 and 5349.
   bashcopy

   # Example iptables rules for forwarding WebRTC ports to 3CX
   iptables -A INPUT -p tcp --dport 5001 -j ACCEPT
   iptables -A INPUT -p udp --dport 9000:10999 -j ACCEPT
   iptables -A INPUT -p udp --dport 3478 -j ACCEPT

3. section #3

   Configuring STUN and TURN for Complex NAT Environments

   Interactive Connectivity Establishment (ICE)

   WebRTC endpoints utilize ICE framework signaling to exchange transport candidates. When both client and server sit behind typical NAT routers, ICE automatically establishes a direct UDP peer-to-peer path using STUN servers.

   Deploying TURN Media Relays

   In strict enterprise environments featuring symmetrical NAT or restrictive egress firewalls, direct UDP path discovery often fails. 3CX utilizes TURN (Traversal Using Relays around NAT) servers to relay media through an intermediary server over UDP or TCP port 3478.

   TURN deployment best practices:

   • Enable the built-in 3CX TURN server or specify an external TURN service in Network Settings.
   • Use custom authentication credentials to prevent unauthorized media relay usage.
   • Ensure external firewall egress policies permit traffic to TURN server ports.
4. section #4

   Provisioning WebRTC Rights for Users and Live Chat

   User Extension Web Client Rights

   Administrators must assign WebRTC usage permissions inside the 3CX Management Console. Navigating to the extension's Rights tab allows toggling browser calling capabilities per user or role.

   Enabling 3CX Live Chat and Talk

   WebRTC powers 3CX Live Chat, enabling website visitors to initiate high-definition audio and video calls straight from their web browser to system queues or extensions without installing additional plug-ins.

   Configuration steps for Live Chat WebRTC:

   • Generate a Live Chat code snippet in the 3CX Console under Settings > Live Chat.
   • Assign incoming web calls to specific Call Center Queues or Ring Groups.
   • Enable video escalation rights to allow agents to convert audio chats into video calls.
   jsoncopy

   {
     "live_chat_config": {
       "enable_video": true,
       "enable_audio": true,
       "target_queue": "Sales_Queue_800",
       "fallback_extension": "100",
       "webrtc_stun_server": "stun-party.3cx.com"
     }
   }

5. section #5

   Troubleshooting WebRTC Media and Connectivity Issues

   Resolving One-Way Audio and Silent Calls

   One-way audio in WebRTC sessions is almost universally caused by unmapped NAT candidates or asymmetric UDP firewall rules. Check your browser's internal WebRTC diagnostics (chrome://webrtc-internals) to verify whether ICE connection state successfully reaches the completed or connected phase.

   Investigating Certificate and WebSocket Errors

   If the 3CX Web Client displays connection warnings or fails to register, inspect the browser's developer console for WebSocket connection failures or untrusted TLS certificate errors.

   Key diagnostic checklist:

   • Certificate Validity: Confirm the SSL certificate chain is complete and not expired.
   • Blocked Ports: Test UDP connectivity on range 9000-10999 using network utility tools like netcat or iperf.
   • Browser Permissions: Verify microphone and camera permissions are explicitly granted in the browser settings.

Further reading

• 3CX Academy: Web Client and WebRTC Configuration
• RFC 8825: Overview: Web Real-Time Communication (WebRTC) Security Architecture
• RFC 8489: Session Traversal Utilities for NAT (STUN)
• RFC 8656: Traversal Using Relays around NAT (TURN)