The OAPPS's  Asterisk phone for Zendesk connects directly from the agent’s browser to your Asterisk or FreePBX server. Before agents can sign in, the PBX must support secure WebSocket signaling and encrypted WebRTC audio.

This article describes the additional PBX configuration required for the Zendesk app. It assumes that your trunks, inbound routes, outbound routes, and dial plan are already working.

Requirements

You will need:

• Asterisk 13 or later with PJSIP and WebRTC support
• A public DNS hostname for the PBX, such as pbx.example.com
• A valid TLS certificate for that hostname
• Network access from each agent’s browser to the PBX
• One PJSIP extension and password for each Zendesk agent

Do not enter a bare IP address in the Zendesk app when using secure WebSockets. The app should connect using the hostname covered by the PBX certificate.

Required FreePBX modules

Confirm the following modules are installed and enabled under Admin → Module Admin:

The following FreePBX modules are not required for the Zendesk phone:

• User Control Panel
• UCP Phone or WebRTC Phone
• EndPoint Manager
• Sangoma Connect
• System Admin, unless it is being used to manage certificates, ports, or other parts of the deployment

The Zendesk app acts as the softphone, so FreePBX’s own browser-phone modules are unnecessary.

At the Asterisk level, the following components must be available:

• res_crypto
• res_http_websocket
• res_pjsip
• res_pjsip_transport_websocket
• codec_opus, recommended where supported

1. Configure the PBX hostname and certificate

Create a DNS record such as:

pbx.example.com

The hostname must resolve to the PBX or to the firewall/reverse proxy that provides access to it.

In FreePBX:

1. Open Admin → Certificate Management.
2. Generate a Let’s Encrypt certificate or import a certificate from a trusted certificate authority.
3. Confirm that the certificate includes the exact hostname agents will enter in the Zendesk app.
4. Set it as the default certificate where appropriate.

A self-signed certificate might be acceptable for controlled testing, but it is not recommended for production. Browsers frequently reject self-signed certificates, resulting in failed WebSocket connections.

2. Enable the Asterisk HTTPS and WebSocket service

Open Settings → Advanced Settings and locate the Asterisk built-in HTTP server settings.

Configure:

After saving the changes, restart Asterisk if FreePBX requests it.

The default secure WebSocket address is normally:

wss://pbx.example.com:8089/ws

If a reverse proxy exposes the service through standard HTTPS port 443, the address may instead resemble:

wss://pbx.example.com/ws

Use the address defined for your deployment.

3. Enable the PJSIP WebSocket transport

Open:

Settings → Asterisk SIP Settings → SIP Settings [chan_pjsip]

Make sure the WebSocket or WSS transport is enabled. Depending on the FreePBX version, it might be displayed as:

• WebSocket transport
• WS transport
• WSS transport
• 0.0.0.0-wss

Select the trusted TLS certificate where the page provides that option.

Apply the configuration and restart Asterisk if requested. Transport changes do not always become active after a normal configuration reload.

4. Check NAT and RTP settings

In Settings → Asterisk SIP Settings, verify:

• External Address contains the PBX’s public address.
• Every internal or VPN network is listed under Local Networks.
• The RTP range is configured. The usual default is UDP ports 10000–20000.
• Opus, ulaw, and alaw are enabled as appropriate.

These settings allow Asterisk to advertise reachable media addresses to browsers connecting from outside the PBX network.

5. Create a WebRTC extension

Open Applications → Extensions and create an Add New PJSIP Extension.

Do not create a chan_sip extension. WebRTC extensions should use PJSIP.

Configure the basic extension fields:

Keeping Direct Media disabled ensures that Asterisk remains in the media path. This is normally necessary when calls pass between WebRTC, SIP trunks, desk phones, recordings, queues, or codecs that require transcoding.

Each Zendesk agent should have a separate extension. Do not share one extension and password between multiple agents.

6. Enable WebRTC on the extension

Open the extension’s Advanced settings and configure:

When Enable WebRTC Defaults works correctly, FreePBX or Asterisk may set several of these values automatically. The resulting PJSIP endpoint should contain the equivalent of:

webrtc=yes
use_avpf=yes
media_encryption=dtls
dtls_verify=fingerprint
dtls_setup=actpass
ice_support=yes
media_use_received_transport=yes
rtcp_mux=yes

Save the extension and click Apply Config.

7. Configure codecs

Enable at least one codec supported by both the browser and Asterisk.

Recommended order:

1. Opus
2. ulaw
3. alaw

Opus provides excellent browser audio quality. Enabling ulaw or alaw can reduce transcoding requirements when communicating with traditional SIP trunks or desk phones.

Avoid configuring the extension with only proprietary codecs such as G.729. Browsers do not normally offer them for WebRTC calls.

8. Configure firewall access

Agents’ browsers must be able to reach:

Only expose the ports used by your deployment. Restrict access to trusted networks or VPN users where practical.

Do not expose the FreePBX administration interface simply because agents need access to the WebRTC phone. The administration interface and WebRTC services should have separate access policies.

9. Configure the Zendesk phone

For each agent, enter the connection details supplied by the PBX administrator:

Use the hostname covered by the TLS certificate. Using the PBX IP address can cause certificate validation to fail even if the certificate itself is valid.

Agents must allow microphone access when the browser requests it.

10. Test the configuration

Test the following for each agent:

1. The Zendesk phone registers successfully.
2. The agent can call another internal extension.
3. The agent can place an external call.
4. An inbound or queue call rings in Zendesk.
5. Audio works in both directions.
6. Hold, mute, transfer, and DTMF work as expected.
7. The extension reconnects after the browser or Zendesk tab is reopened.

Troubleshooting

The phone does not register

Check:

• The extension is PJSIP.
• The extension number and secret are correct.
• The application uses wss://, not ws://.
• The hostname matches the certificate.
• The WSS transport is enabled.
• TCP port 8089, or the configured proxy port, is reachable.
• Force WebSocket Mode is set to PJSIP.
• Asterisk was restarted after changing the transport.

The browser reports a WebSocket or certificate error

The usual causes are:

• An expired or self-signed certificate
• A certificate issued for a different hostname
• Using an IP address instead of the certificate hostname
• Connecting with insecure ws:// from the HTTPS Zendesk interface
• A firewall or reverse proxy that is not passing WebSocket upgrades

Calls connect but there is no audio

Check:

• The PBX external address
• Local network definitions
• The RTP UDP port range
• Firewall and NAT rules
• ICE support on the extension
• DTLS-SRTP settings
• Browser microphone permissions

If agents are behind restrictive corporate networks, symmetric NAT, or networks that block UDP, the application may also require a TURN server.

Outbound calls fail

WebRTC registration does not grant dialing permission by itself. Check the extension’s context, outbound routes, route permissions, dial patterns, and trunk configuration.

Inbound calls do not reach the agent

Check the inbound route, queue membership, ring group, time conditions, and the dial plan destination assigned to the extension.

Security recommendations

• Assign a unique extension and password to every agent.
• Use long, randomly generated extension secrets.
• Keep FreePBX and Asterisk updated with current security fixes.
• Do not allow anonymous SIP calls unless they are explicitly required.
• Restrict the FreePBX administration interface to trusted networks.
• Use a VPN or trusted-source firewall rules where practical.
• Disable extensions immediately when an agent no longer requires access.
• Monitor failed registrations and unexpected international calling activity.

WebRTC makes the PBX reachable from agents’ browsers, so it should be treated as a remote-access service and protected accordingly.

References

• Asterisk: Configuring WebRTC clients
• Asterisk PJSIP endpoint options
• FreePBX Certificate Management
• FreePBX Asterisk SIP Settings