Asterisk WebRTC Setup: WSS Transport, Certificates, webrtc=yes

Short answer: Browsers talk to Asterisk over secure WebSocket (WSS) for signalling and DTLS-SRTP for media. You need four things: a TLS certificate the browser trusts, the Asterisk HTTP server with TLS enabled (port 8089 by convention, path /ws), a PJSIP transport with protocol=wss, and endpoints with webrtc=yes and a codec browsers support (Opus or G.711). Then point a JavaScript SIP client at wss://pbx.example.com:8089/ws.

Configuration follows the official Asterisk WebRTC guide (linked below), checked on 6 October 2026. On our lab server (Debian 12, FreePBX 17.0.33, Asterisk 22.11) we confirmed the required modules and the HTTP/WebSocket status commands; we did not register a browser client there.

Requirements

• Asterisk 15.5 or later with chan_pjsip, per the official guide. Any current LTS (20 or 22) qualifies.
• Modules: res_crypto, res_http_websocket, res_pjsip_transport_websocket, and codec_opus (recommended).
• A DNS name for the PBX, for example pbx.example.com, and a certificate for it. Browsers will not keep a WSS connection to a self-signed certificate unless the user accepts it first.
• Firewall: TCP 8089 (WSS) from your users, plus the RTP range over UDP.

Check the modules:

asterisk -rx "module show like websocket"
asterisk -rx "module show like opus"
asterisk -rx "module show like res_crypto"

On our FreePBX 17 lab all of these were loaded, including res_pjsip_transport_websocket.so, res_http_websocket.so and codec_opus.so.

Get a certificate

A certificate from a public CA (for example Let’s Encrypt) avoids browser warnings and is what you want for real users. Point tlscertfile at the full-chain certificate and tlsprivatekey at the key, and make sure the asterisk user can read both. After each renewal, reload or restart Asterisk so it reads the new files.

For a lab, the Asterisk source tree includes a helper script that creates a self-signed CA and certificate. This is the command from the official guide, run from the source directory:

sudo mkdir /etc/asterisk/keys
sudo contrib/scripts/ast_tls_cert -C pbx.example.com -O "My Organization" -b 2048 -d /etc/asterisk/keys

It writes asterisk.crt and asterisk.key into /etc/asterisk/keys. Package-based installs may not ship the script; on our FreePBX lab it was not on disk. Check certificate dates and chain afterwards with our SSL certificate checker.

Enable the HTTPS and WebSocket server (http.conf)

Asterisk’s built-in HTTP server terminates the WebSocket. The official example:

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

The plain HTTP port is not needed by browsers; bind it to 127.0.0.1 if you only use it locally. After restarting Asterisk, http show status must show HTTPS bound on 8089 and the /ws URI enabled. This is the output from our FreePBX 17 lab:

HTTP Server Status:
Prefix:
Server: Asterisk/22.11.0
Server Enabled and Bound to 127.0.0.1:8088

HTTPS Server Enabled and Bound to 127.0.0.1:8089

Enabled URI's:
/metrics/... => Prometheus Metrics URI
/media/... => Media over Websocket
/ws => Asterisk HTTP WebSocket

Note the binding: on our FreePBX 17 lab both servers listened on 127.0.0.1 only, so browsers elsewhere could not connect. On FreePBX, the HTTP settings are managed by FreePBX (the file is http_additional.conf), so change them through its settings rather than editing the generated file.

Add a WSS transport and a WebRTC endpoint (pjsip.conf)

The transport, from the official guide:

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

WebSocket connections arrive through the HTTP server configured above. The Asterisk sample pjsip.conf notes that for the WebSocket transport the TLS configuration lives in http.conf and applies to all HTTPS traffic, so the certificate and port come from there. Transport changes need a full Asterisk restart; a reload is not enough.

Then an endpoint with its AOR and auth. Use a strong password and a context that cannot reach outbound routes unless the user needs them:

[webrtc_client]
type=aor
max_contacts=5
remove_existing=yes

[webrtc_client]
type=auth
auth_type=userpass
username=webrtc_client
password=CHANGE_ME_long_random

[webrtc_client]
type=endpoint
aors=webrtc_client
auth=webrtc_client
dtls_auto_generate_cert=yes
webrtc=yes
context=default
disallow=all
allow=opus,ulaw

webrtc=yes is a shortcut. According to the Asterisk 22 option documentation it enables rtcp_mux, use_avpf, ice_support and use_received_transport, and defaults media_encryption=dtls, dtls_verify=fingerprint, dtls_setup=actpass, plus dtls_auto_generate_cert=yes when no dtls_cert_file is set. Browsers require all of these, which is why a normal SIP endpoint profile does not work for WebRTC.

max_contacts=5 with remove_existing=yes lets the user open several browser tabs and replaces stale ones, because each page load registers a new contact.

Connect a browser client

The browser needs a JavaScript SIP stack. The Asterisk project documents its own demo client, CyberMegaPhone, and widely used libraries include SIP.js and JsSIP. Whatever you choose, the settings are the same:

Client setting	Value
WebSocket server	wss://pbx.example.com:8089/ws
SIP URI / user	sip:webrtc_client@pbx.example.com
Auth user / password	from the type=auth section
Media	microphone permission granted; the page itself must be served over HTTPS

With a self-signed certificate, open https://pbx.example.com:8089/ws in the browser once and accept the warning, as the official guide suggests; otherwise the WebSocket connection fails silently.

Check that it worked

asterisk -rx "http show status"
asterisk -rx "pjsip show transports"
asterisk -rx "pjsip show contacts like webrtc"
asterisk -rx "pjsip show endpoint webrtc_client"

• http show status: HTTPS bound on 8089 on an address the browser can reach, and /ws listed.
• pjsip show transports: transport-wss listed with type wss.
• After the client registers, pjsip show contacts like webrtc lists a contact for the endpoint with status Avail or NonQual.
• Place a call from the browser to a test extension and check two-way audio. pjsip set logger on shows the INVITE with DTLS fingerprint lines in the SDP.

Common problems

• WebSocket connection fails at once: certificate not trusted (accept it, or use a CA certificate), wrong port, or HTTPS bound to 127.0.0.1.
• Registers, but calls fail with 488: no common codec, or the endpoint lacks webrtc=yes so DTLS/AVPF are not offered.
• Call connects, no audio: ICE cannot find a path. If Asterisk is behind NAT, configure the external media address on the transport and STUN in rtp.conf; open the RTP range. Our one-way audio guide covers the checks.
• Works until the certificate renews, then fails: make sure your renewal hook copies the new files where Asterisk reads them and reloads or restarts Asterisk.

Official documentation: Asterisk: Configuring Asterisk for WebRTC Clients · Asterisk: Installing and Configuring CyberMegaPhone · Asterisk: res_pjsip configuration options

Related: Install Asterisk 22 LTS on Debian 13: Step-by-Step Guide · SSL Certificate Checker · VoIP One-Way Audio Fix: 6 Checks for NAT and RTP · PJSIP Behind NAT: Asterisk and FreePBX Settings for Two-Way Audio · SIP Ports Firewall Rules: 4 Setups for CSF, firewalld and pfSense

See also: Asterisk AudioSocket: Connect a Call to an AI Voice Agent · Asterisk Versions and EOL Dates: LTS Support Table and Upgrade Plan

Frequently asked questions