Vicidial® WebRTC phone setup — browser-based agent extension

The Vicidial® WebRTC phone lets agents work from a browser without installing a softphone — no Zoiper, no MicroSIP, no admin needing to do an endpoint provisioning setup. ViciBox® bundles the necessary pieces; this article walks the configuration steps after deployment.

Prerequisites

• ViciBox VPS deployed (the LYLIX ViciBox image has everything needed pre-installed).
• Valid TLS certificate for the Vicidial admin URL — WebRTC requires HTTPS + WSS. Self-signed certs work for testing only; production needs a real cert (Let's Encrypt is the standard answer; see the related TLS article).
• Public IP reachable on:
  • HTTPS port 443 (admin GUI + WSS signaling)
  • RTP media ports (default 10000-20000 UDP)

Configure WSS in Asterisk

The Vicidial WebRTC phone uses WebSocket Secure (WSS) for SIP signaling. ViciBox's default Asterisk configures HTTP server with TLS; verify /etc/asterisk/http.conf:

[general]
enabled=yes
bindaddr=0.0.0.0
bindport=8088
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/letsencrypt/live/vicibox.example.com/fullchain.pem
tlsprivatekey=/etc/letsencrypt/live/vicibox.example.com/privkey.pem

Reload Asterisk: asterisk -rx "core reload". Verify HTTP server is up:

asterisk -rx "http show status"

Should show TLS Enabled = Yes, listening on 8089.

WebRTC-friendly PJSIP endpoint config

WebRTC phone extensions need specific PJSIP settings — different from a hardphone or softphone:

[6001](!)
type=endpoint
context=default
disallow=all
allow=opus,ulaw
transport=transport-wss
webrtc=yes
use_avpf=yes
media_encryption=dtls
dtls_verify=fingerprint
dtls_setup=actpass
dtls_cert_file=/etc/letsencrypt/live/vicibox.example.com/fullchain.pem
ice_support=yes
rtcp_mux=yes
auth=6001
aors=6001

[transport-wss]
type=transport
protocol=wss
bind=0.0.0.0:8089

For ViciBox specifically, the WebRTC agent extensions are configured automatically when you toggle WebRTC = YES on the agent's user profile in the admin UI.

Agent login flow

1. Agent opens https://vicibox.example.com/agc/vicidial.php.
2. Logs in with their Vicidial agent credentials.
3. Selects a campaign + WebRTC phone option.
4. Browser requests microphone access (must accept).
5. WebRTC phone registers with the Vicidial server. Status shows "Ready" once registered.

Test by setting a small test campaign + dialing a manual outbound. Browser plays inbound audio, mic captures outbound.

Browser support

• Chrome / Edge: works well. Recommended.
• Firefox: works. Occasional codec negotiation quirks.
• Safari: works on macOS 13+, less reliable on iOS.
• Mobile browsers: technically work but agent UI isn't optimized for small screens — use a desktop or laptop.

Common breakages

• "WebRTC failed to register" — usually TLS cert mismatch. The cert served on port 8089 must match the WSS URL the browser connects to. Self-signed certs fail in modern browsers.
• Registration succeeds but no audio — RTP ports blocked. Open 10000-20000 UDP on the VPS firewall.
• "Audio is one-way" (agent hears caller, caller doesn't hear agent) — microphone permission denied, OR NAT issue if your VPS is behind an unusual network setup. LYLIX VPSes are typically not behind NAT, so check mic permission first.
• Quality is choppy — agent's home internet is the usual culprit. WebRTC needs 80-100 kbps sustained per call + low jitter. Wired connection always beats WiFi.

Failover to softphone

Some operations let agents choose WebRTC OR softphone (Zoiper, MicroSIP) per shift. Agents on poor internet who struggle with WebRTC quality can fall back to a softphone (which is more codec-flexible and less browser-quirk-prone). Both register against the same Vicidial extension; agent selects "WebRTC" or "external" at login.

TURN server (when STUN isn't enough)

WebRTC behind restrictive corporate NAT may need a TURN server to relay media. For agents working from corporate offices with strict firewalls, set up coturn on the VPS and configure the WebRTC client to use it. For typical home / residential ISP setups, STUN (built into WebRTC) is enough; TURN is only needed for hard NAT scenarios.