Getting WebRTC Working in VICIdial Without Losing a Weekend

The complete technical guide to running VICIdial with WebRTC-based softphones — from SSL certificates to PJSIP configuration to the NAT traversal nightmares that make remote agent deployments interesting. --- Remote agents are no longer the exception. They're the majority. In most call center operations we manage, 60-80% of agents work from home or from distributed locations. The days of a physical call center floor with IP desk phones on every desk are fading. VICIdial supports remote agents through WebRTC — specifically through ViciPhone, the built-in browser-based softphone that lets agents take calls directly in their web browser without installing any software. No SIP softphone to configure. No VPN to troubleshoot. No port forwarding on the agent's home router. The agent opens a browser, logs in, and starts taking calls. When it works, WebRTC is elegant. When it doesn't work, you'll spend hours chasing one-way audio, certificate errors, and the kind of NAT traversal problems that make experienced sysadmins question their career choices. This guide covers the full WebRTC setup for VICIdial: server requirements, SSL configuration, PJSIP vs. SIP channel driver considerations, Asterisk WebSocket configuration, ViciPhone settings, NAT traversal (STUN/TURN), codec selection, scaling for large remote workforces, and troubleshooting every common issue. For the WebRTC glossary entry, see /glossary/webrtc/. --- ## How WebRTC Works in VICIdial Before configuring anything, understand the architecture. WebRTC in VICIdial has three components: 1. ViciPhone (the browser client). This is a JavaScript-based SIP client built into VICIdial's agent interface. It runs in the agent's browser and handles the audio connection. ViciPhone uses the JsSIP library (or a modified version of it) to implement SIP signaling over WebSocket and audio transport via WebRTC. 2. Asterisk (the media server). Asterisk handles the actual SIP registration, call routing, and media processing. For WebRTC, Asterisk must be configured to accept WebSocket connections (WSS — WebSocket Secure) for SIP signaling and DTLS-SRTP for encrypted media transport. 3. The signaling path. When an agent loads ViciPhone, the browser establishes a WebSocket connection to Asterisk on a designated port (typically 8089 for WSS). SIP REGISTER and INVITE messages travel over this WebSocket. Audio media (RTP) is negotiated via ICE (Interactive Connectivity Establishment) and flows as encrypted SRTP between the browser and Asterisk. The key constraint: WebRTC requires HTTPS. Modern browsers will not allow WebRTC media access (microphone) on non-secure origins. Your VICIdial web interface must be served over HTTPS with a valid SSL certificate. Self-signed certificates will cause problems — browsers either block WebRTC entirely or require users to manually accept certificate exceptions, which breaks the agent experience. --- ## Server Requirements ### Operating System and Asterisk Version - ViciBox 12.0.2+ (AlmaLinux 9 based): Recommended. Comes with Asterisk 18 LTS or 20 and PJSIP compiled. - AlmaLinux 9 / Rocky Linux 9 with manual install: Works, but you must ensure Asterisk is compiled with res_pjsip, res_pjsip_transport_websocket, and res_http_websocket modules. - Asterisk version: 18 LTS or 20. Asterisk 16 works but has known WebSocket stability issues. Asterisk 13 requires significantly more manual configuration and is not recommended for new WebRTC deployments. Required Asterisk modules: res_pjsip.so res_pjsip_transport_websocket.so res_http_websocket.so res_pjsip_dtls.so res_pjsip_sdp_rtp.so codec_opus.so (recommended) Verify modules are loaded: bash asterisk -rx "module show like pjsip" asterisk -rx "module show like websocket" asterisk -rx "module show like opus" ### HTTPS and SSL Certificate You need a valid, publicly-trusted SSL certificate. Let's Encrypt is free and works perfectly: bash # Install certbot sudo dnf install -y certbot # Obtain certificate (your VICIdial server must be publicly accessible on port 80) sudo certbot certonly --standalone -d vicidial.yourdomain.com # Certificate files will be at: # /etc/letsencrypt/live/vicidial.yourdomain.com/fullchain.pem # /etc/letsencrypt/live/vicidial.yourdomain.com/privkey.pem Automatic renewal: bash # Add to crontab echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload httpd && asterisk -rx \"module reload res_pjsip.so\"'" | sudo crontab - The --post-hook restarts Apache and reloads PJSIP after certificate renewal, ensuring Asterisk picks up the new certificate without a service interruption. Important: The SSL certificate must cover the hostname that agents use to access VICIdial. If agents connect to vicidial.yourdomain.com, the certificate must be issued for that exact hostname. Wildcard certificates (*.yourdomain.com) also work. ### Apache HTTPS Configuration Configure Apache to serve VICIdial over HTTPS: apache # /etc/httpd/conf.d/ssl.conf (or site-specific config) <VirtualHost *:443> ServerName vicidial.yourdomain.com DocumentRoot /var/www/html SSLEngine on SSLCertificateFile /etc/letsencrypt/live/vicidial.yourdomain.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/vicidial.yourdomain.com/privkey.pem # Recommended SSL settings SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 SSLCipherSuite HIGH:!aNULL:!MD5 SSLHonorCipherOrder on # WebSocket proxy (if proxying through Apache) ProxyPass /ws wss://127.0.0.1:8089/ws ProxyPassReverse /ws wss://127.0.0.1:8089/ws # Standard VICIdial config <Directory /var/www/html> AllowOverride All Require all granted </Directory> </VirtualHost> # Redirect HTTP to HTTPS <VirtualHost *:80> ServerName vicidial.yourdomain.com Redirect permanent / https://vicidial.yourdomain.com/ </VirtualHost> Enable required Apache modules: bash # These are typically already available on AlmaLinux 9 sudo dnf install -y mod_ssl sudo systemctl restart httpd --- ## PJSIP vs. SIP Channel Driver for WebRTC VICIdial historically used the chan_sip channel driver. WebRTC support works with both chan_sip and chan_pjsip, but PJSIP is the recommended choice for WebRTC deployments: | Feature | chan_sip | chan_pjsip (PJSIP) | |---|---|---| | WebSocket transport | Requires res_http_websocket + manual config | Native res_pjsip_transport_websocket | | DTLS-SRTP | Limited support | Full native support | | ICE negotiation | Partial | Full native support | | Multiple transports per endpoint | No | Yes (UDP + WSS on same endpoint) | | Asterisk development status | Deprecated (removed in Asterisk 21) | Actively maintained | | VICIdial compatibility | Full (legacy) | Full (current) | If you're setting up a new VICIdial installation or upgrading, use PJSIP. If you're running an existing chan_sip installation and adding WebRTC, you can either migrate to PJSIP or configure WebRTC on chan_sip — but be aware that chan_sip is deprecated and will not be available in future Asterisk versions. The rest of this guide assumes PJSIP configuration. For chan_sip WebRTC setup, the concepts are similar but the configuration file format differs. --- ## Asterisk Configuration for WebRTC ### http.conf — Enable the HTTP Server and WebSocket Asterisk's built-in HTTP server handles WebSocket connections. Configure it in /etc/asterisk/http.conf: ini [general] enabled=yes bindaddr=0.0.0.0 bindport=8088 tlsenable=yes tlsbindaddr=0.0.0.0:8089 tlscertfile=/etc/letsencrypt/live/vicidial.yourdomain.com/fullchain.pem tlsprivatekey=/etc/letsencrypt/live/vicidial.yourdomain.com/privkey.pem Key settings: - tlsenable=yes — Enables HTTPS/WSS on port 8089 - tlscertfile and tlsprivatekey — Must point to the same SSL certificate used by Apache. Using a different certificate will cause certificate mismatch errors in the browser. - bindport=8088 — HTTP (non-TLS) on port 8088. Used for internal health checks but should not be exposed to the internet. - Port 8089 (WSS) must be accessible from agents' networks. If agents are remote, this port must be open through your firewall. Reload the HTTP module: bash asterisk -rx "module reload res_http_websocket.so" Verify the HTTP server is running: bash asterisk -rx "http show status" You should see both HTTP (8088) and HTTPS (8089) listeners active. ### pjsip.conf — WebSocket Transport and Endpoint Configuration The PJSIP configuration is where most of the WebRTC-specific settings live. On VICIdial/ViciBox installations, PJSIP configuration may be managed through the database (via table_config entries) or directly in /etc/asterisk/pjsip.conf. Check your installation — ViciBox uses database-driven configuration by default. #### Transport Configuration Define a WebSocket Secure (WSS) transport: ini ; /etc/asterisk/pjsip.conf (or via VICIdial admin → PJSIP settings) [transport-wss] type=transport protocol=wss bind=0.0.0.0:8089 cert_file=/etc/letsencrypt/live/vicidial.yourdomain.com/fullchain.pem priv_key_file=/etc/letsencrypt/live/vicidial.yourdomain.com/privkey.pem ; For self-signed certs during testing (not recommended for production): ; verify_client=no ; verify_server=no ; Also keep your UDP transport for SIP trunks [transport-udp] type=transport protocol=udp bind=0.0.0.0:5060 #### WebRTC Endpoint Template Create a template for WebRTC agent endpoints: ini [webrtc-endpoint](!) type=endpoint transport=transport-wss context=default disallow=all allow=opus allow=g722 allow=ulaw dtls_auto_generate_cert=yes webrtc=yes ; The webrtc=yes shorthand sets: ; use_avpf=yes ; media_encryption=dtls ; dtls_verify=fingerprint ; dtls_setup=actpass ; ice_support=yes ; media_use_received_transport=yes ; rtcp_mux=yes The webrtc=yes setting (available in Asterisk 16+) is a convenience option that configures all the necessary DTLS, ICE, AVPF, and RTCP multiplexing settings in a single line. Without it, you'd need to set each of those individually. #### Agent Endpoint Configuration For each VICIdial phone entry used by WebRTC agents, the PJSIP endpoint configuration is typically managed through VICIdial's admin interface under Admin → Phones. When creating a phone entry for a WebRTC agent: - Server: Your Asterisk server IP - Dialplan Number: The extension number (e.g., 8000-8999 range for WebRTC phones) - Protocol: PJSIP - Registration: Include WebRTC-specific parameters VICIdial generates the PJSIP configuration entries from the phone table. After adding or modifying phone entries, reload PJSIP: bash asterisk -rx "pjsip reload" Verify the endpoint is configured: bash asterisk -rx "pjsip show endpoints" asterisk -rx "pjsip show endpoint [endpoint-name]" --- ## VICIdial Admin Configuration for WebRTC ### System Settings In Admin → System Settings, configure WebRTC-related parameters: - WebRTC Phone Enabled: Y - WebSocket URL: wss://vicidial.yourdomain.com:8089/ws The WebSocket URL is what ViciPhone uses to establish the SIP signaling connection. It must match your Asterisk http.conf TLS bind address and the hostname on your SSL certificate. ### Phone Configuration For each remote agent using WebRTC, create a Phone entry under Admin → Phones: - Extension: Unique extension number (e.g., 8001) - Server IP: Your Asterisk/dialer server IP - Dialplan Number: Same as extension - Phone Type: Use the WebRTC-compatible type - Protocol: PJSIP (or SIP if using chan_sip) - Registration String: The PJSIP registration parameters. VICIdial auto-generates this for WebRTC-enabled phones. ### Agent Interface — ViciPhone When an agent logs into the VICIdial agent interface on a WebRTC-enabled phone, ViciPhone automatically loads in the browser. The agent sees: - A phone status indicator (registered/unregistered) - Volume controls - A dial pad (for manual dialing if enabled) - Call state indicators ViciPhone v3.0 (available in recent SVN revisions) includes improvements over earlier versions: - Better ICE candidate handling for NAT traversal - Opus codec support for better audio quality at lower bandwidth - Improved reconnection logic when WebSocket connections drop - Audio level monitoring (helps diagnose one-way audio issues) - Echo cancellation improvements The agent doesn't need to do anything special — ViciPhone initializes automatically when they log in with a WebRTC-enabled phone assignment. The browser will prompt for microphone permission on first use; the agent must click "Allow." --- ## NAT Traversal: STUN and TURN Servers NAT traversal is the single biggest source of WebRTC problems in VICIdial remote agent deployments. Here's why and how to solve it. ### The Problem Most remote agents are behind residential NAT routers. Their computer has a private IP address (192.168.x.x or 10.x.x.x) that isn't directly reachable from the internet. WebRTC needs to establish a direct media path between the agent's browser and the Asterisk server. Without NAT traversal assistance, the browser and Asterisk can't figure out how to route audio packets to each other. This manifests as: - One-way audio: The agent can hear the caller, but the caller can't hear the agent (or vice versa) - No audio at all: Call connects (SIP signaling works over WebSocket) but no audio flows - Audio works briefly then drops: ICE candidates expire or NAT mappings time out ### STUN Servers STUN (Session Traversal Utilities for NAT) servers help WebRTC clients discover their public IP address and the type of NAT they're behind. STUN is sufficient for most residential NAT setups (cone NAT, restricted cone NAT). Google's public STUN servers (free, reliable, widely used): stun:stun.l.google.com:19302 stun:stun1.l.google.com:19302 stun:stun2.l.google.com:19302 Configure STUN servers in VICIdial's WebRTC/ViciPhone settings. The specific location depends on your VICIdial version — check Admin → System Settings or the ViciPhone JavaScript configuration. In Asterisk's pjsip.conf, configure the STUN server for ICE: ini [global] type=global [system] type=system ; Or in the transport section: [transport-wss] type=transport protocol=wss bind=0.0.0.0:8089 cert_file=/etc/letsencrypt/live/vicidial.yourdomain.com/fullchain.pem priv_key_file=/etc/letsencrypt/live/vicidial.yourdomain.com/privkey.pem external_media_address=YOUR_PUBLIC_IP external_signaling_address=YOUR_PUBLIC_IP The external_media_address and external_signaling_address settings tell Asterisk to advertise its public IP (not its private IP) in SIP/SDP messages. This is essential when Asterisk is behind a NAT or firewall. ### TURN Servers STUN doesn't work for symmetric NAT — the kind found in some corporate firewalls and carrier-grade NAT (CGNAT) deployments. For these cases, you need a TURN (Traversal Using Relays around NAT) server. TURN relays media traffic through a server when direct peer-to-peer

Read the full article

About

Built by ViciStack — enterprise VoIP and call center infrastructure.

• VICIdial Hosting & Optimization
• Call Center Performance Guides
• Full Article: Getting WebRTC Working in VICIdial Without Losing a Weekend

License

MIT