WebRTC agent stations on ViciBox — WSS transport, TURN, browser-side limitations

WebRTC turns the agent's browser into the SIP endpoint — no hardphone, no softphone install, no audio driver support calls. ViciBox® ships ready for this; the gating items are a real TLS cert on the web endpoint and (for some agent network profiles) a TURN server. This article walks the configuration end-to-end plus the failure modes that send you back to hardphones.

What needs to be in place

1. Real TLS certificate covering the FQDN agents will connect to. Self-signed will be rejected by every modern browser for WSS — no opt-out dialog.
2. Asterisk® HTTPS endpoint with WSS bind enabled.
3. A Vicidial® phone record per agent with protocol=WEBRTC.
4. Agent browser pointed at the Vicidial agent URL over HTTPS (not HTTP).
5. If your agents are behind symmetric NAT (common with carrier-grade NAT on mobile broadband, less common on residential NAT), a TURN server. Skip until you see the failure.

TLS certificate

Point your hostname at the VPS, then on the ViciBox:

zypper install certbot python-certbot-apache
certbot --apache -d agent.example.com

certbot writes the cert into /etc/letsencrypt/live/ and updates Apache. Verify https://agent.example.com/vicidial/ loads cleanly in a browser — no certificate warning.

Asterisk's HTTPS endpoint uses a separate cert config from Apache. Copy or symlink:

cp /etc/letsencrypt/live/agent.example.com/fullchain.pem \
   /etc/asterisk/keys/agent.crt
cp /etc/letsencrypt/live/agent.example.com/privkey.pem \
   /etc/asterisk/keys/agent.key
chown asterisk:asterisk /etc/asterisk/keys/agent.*

Set up a certbot deploy hook to repeat the copy on cert renewal — otherwise the cert silently expires in 90 days and WSS stops working without a clear error.

Asterisk HTTP / WSS configuration

/etc/asterisk/http.conf:

[general]
enabled=yes
bindaddr=0.0.0.0
bindport=8088
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/asterisk/keys/agent.crt
tlsprivatekey=/etc/asterisk/keys/agent.key

And in /etc/asterisk/sip.conf (or wherever your transports live):

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

Reload Asterisk: asterisk -rx "core reload". Verify:

asterisk -rx "http show status"
asterisk -rx "sip show settings" | grep -i wss

Should show WSS as a listening transport on 8089.

Open the firewall

WSS on TCP/8089 needs to be reachable from the agent's network. From the LYLIX portal's firewall tab, ensure TCP/8089 is open inbound. If you only want to allow known agent networks, restrict to those source CIDRs.

RTP media uses ports 10000-20000 UDP by default (Asterisk's rtp.conf). All open by default on LYLIX VPS; restrict if your threat model requires it.

Vicidial phone record

Admin → Phones → Add a New Phone:

• Extension: numeric (e.g. 1001)
• Login: same numeric (e.g. 1001)
• Pass: a strong password the agent will not see
• Protocol: EXTERNAL with the Phone Context set per your dialplan, OR SIP with the appropriate transport set on the user's softphone — the Vicidial codebase uses SIP records for WebRTC agents and the discriminator is the user's browser using the WSS transport, not a separate Vicidial protocol field
• Active: Y
• User Group: assign to the same group your agents are in

The Vicidial agent record (User → Modify → Phone Login) should reference this phone's extension. When the agent logs into the agent.php interface, the embedded WebRTC client registers against the WSS endpoint using these creds.

Agent-side test

1. Agent opens https://agent.example.com/agc/vicidial.php
2. Enters their Vicidial user creds + phone login extension (1001) + phone password
3. Click "Submit" — first time, browser prompts for microphone permission. Allow.
4. Agent interface loads. The phone status should show green / registered within ~5 seconds.
5. Click "Test Call" or use a campaign in Manual mode to place a call to a known number. Agent should hear ringback and audio.

TURN — when you need it

WebRTC tries direct peer-to-peer first (using STUN to discover its public IP), and falls back to TURN if direct fails. The classical case that needs TURN:

• Agent is on a corporate network with symmetric NAT or outbound firewall that blocks UDP entirely.
• Agent is on mobile broadband behind carrier-grade NAT (CGNAT), common in 2026 for both mobile and fiber-to-the-home in many markets.
• Agent and the ViciBox VPS are on the same NAT (rare for hosted ViciBox but possible if you tunnel for some reason).

Symptom: agent registers fine, dials, hears nothing (one-way audio or no audio at all). Diagnose:

asterisk -rx "rtp set debug ip <agent-ip>"

Look at the RTP packet flow. If outbound packets go but none come back, the agent's NAT is eating the inbound stream and you need TURN.

Set up coturn on the ViciBox VPS (or a separate small VPS):

zypper install coturn
# /etc/coturn/turnserver.conf:
listening-port=3478
tls-listening-port=5349
fingerprint
use-auth-secret
static-auth-secret=<long-random-string>
realm=agent.example.com
cert=/etc/asterisk/keys/agent.crt
pkey=/etc/asterisk/keys/agent.key
no-cli
no-tlsv1
no-tlsv1_1
systemctl enable --now coturn

Configure the Vicidial WebRTC client's ICE servers to include your TURN URL with the auth-secret-derived credentials. The Vicidial agent.php code includes a configuration block for this — search for iceServers in /var/www/agc/conf_phone.php (or its locally overridable equivalent).

Browser-side limitations

• Background tab throttling. Chrome throttles JavaScript timers on background tabs after ~5 minutes. The Vicidial WebRTC heartbeat stops firing; the agent loses bridges silently. Agents must keep the Vicidial tab in the foreground.
• Battery-saver power modes. Laptops on battery sometimes throttle CPU enough that audio processing introduces jitter. Plug in.
• Microphone permission persistence. If the agent ever clicks "Block" on the microphone prompt, they'll need to manually re-enable in browser site settings. Document this.
• Auto-update browser breakage. Approximately twice a year a Chrome major version changes WebRTC behavior in ways that break some deployment. Keep an eye on the Vicidial forum the week of a Chrome major release.

When to give up on WebRTC and go hardphone

If you've burned a week on TURN configuration, your agents report intermittent audio drops, and you're seeing 1-2% bridges where the agent says "I couldn't hear them" — switch the affected agents to MicroSIP softphones or hardphones. WebRTC's failure modes are subtle and don't appear in any log; eliminating it as a variable simplifies diagnosis.