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

Source: https://srvscripts.com/guides/asterisk-webrtc-setup/
Updated: 2026-10-06
Publisher: srvScripts (https://srvscripts.com/)

**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](/tools/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](/guides/voip-one-way-audio/) 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](https://docs.asterisk.org/Configuration/WebRTC/Configuring-Asterisk-for-WebRTC-Clients/) · [Asterisk: Installing and Configuring CyberMegaPhone](https://docs.asterisk.org/Configuration/WebRTC/Installing-and-Configuring-CyberMegaPhone/) · [Asterisk: res_pjsip configuration options](https://docs.asterisk.org/Latest_API/API_Documentation/Module_Configuration/res_pjsip/)

**Related:** [Install Asterisk 22 LTS on Debian 13: Step-by-Step Guide](/guides/install-asterisk-22-debian/) · [SSL Certificate Checker](/tools/ssl-certificate-checker/) · [VoIP One-Way Audio Fix: 6 Checks for NAT and RTP](/guides/voip-one-way-audio/) · [PJSIP Behind NAT: Asterisk and FreePBX Settings for Two-Way Audio](/guides/pjsip-nat-asterisk-freepbx/) · [SIP Ports Firewall Rules: 4 Setups for CSF, firewalld and pfSense](/guides/sip-ports-firewall/)

**See also:** [Asterisk AudioSocket: Connect a Call to an AI Voice Agent](/guides/asterisk-audiosocket-ai-voice-agent/) · [Asterisk Versions and EOL Dates: LTS Support Table and Upgrade Plan](/guides/asterisk-versions-eol-upgrade/)

## Frequently asked questions

### Which port does Asterisk WebRTC use?

WSS signalling runs on the Asterisk HTTPS server, conventionally TCP 8089 with the path /ws. Media uses the normal RTP UDP range.

### What does webrtc=yes do in pjsip.conf?

It turns on rtcp_mux, AVPF, ICE and use_received_transport, and defaults DTLS-SRTP media encryption with fingerprint verification and an auto-generated DTLS certificate.

### Can I use a self-signed certificate for WebRTC?

For testing, yes, but each browser must accept it first by visiting https://pbx.example.com:8089/ws. For real users, use a certificate from a public CA.

### Which codecs should WebRTC endpoints allow?

Opus and G.711 (ulaw or alaw). Browsers support both; Opus gives better quality over the internet.

### Do I need to restart Asterisk after adding the WSS transport?

Yes. PJSIP transport changes only take effect after a full restart, not a reload.