How to set up the ViciPhone WebRTC softphone

ViciPhone is a free, open-source Webphone that works natively with VICIdial. A webphone is a softphone that runs in the browser, so the agent does not install a separate desktop app or fiddle with audio drivers. It uses WebRTC, the browser's built-in voice standard, to carry audio directly between the agent's tab and your Asterisk server. This post walks the setup end to end so you know exactly what has to be in place before an agent can log in and take calls from a browser, and so you can tell which step is missing when one will not register.

The three things you need first

There are three requirements, and the phone will not register without all three in place. First, every Asterisk server in your setup must be version 13 or higher, because browser WebRTC support landed in that release. Second, you need authentic SSL certificates on every Asterisk server and webserver an agent logs into. Browsers refuse microphone access and secure WebSocket connections to a host they do not trust, so a real certificate is not optional. Third, you set up a conf file template for each phone entry in VICIdial that you want to act as a WebRTC phone. Miss any one of these and the symptom is the same frustrating silence: the phone loads but never comes up.

• Asterisk 13 or higher on every server, including any remote ones agents might reach.
• Genuine SSL certificates on each Asterisk server and webserver agents log into.
• A conf file template per phone entry you want to run as a WebRTC phone.

How a browser phone connects

When an agent opens the screen, the browser opens a secure WebSocket to Asterisk and registers as a SIP endpoint. SIP, the Session Initiation Protocol, handles the call signalling, while the actual audio rides over RTP, the protocol that carries the media stream once a call connects. Because everything runs over TLS, the certificate handshake happens before any SIP traffic at all, which is why a self-signed or missing certificate stops the phone cold long before it ever tries to register. If the agent's browser shows a security warning when it loads the page, that is your problem in plain sight.

flowchart LR
  A[Agent browser] --> B[TLS handshake with valid cert]
  B --> C[Secure WebSocket to Asterisk 13]
  C --> D[SIP register from conf template]
  D --> E[RTP audio to the call]

Wiring the phone entry

Each phone in VICIdial is a SIP endpoint with a login and a secret, and the conf file template tells Asterisk how to build that endpoint as a WebRTC peer rather than a plain SIP (Session Initiation Protocol) device. You create one template per phone you want browser-enabled, so if you have twenty agents on WebRTC you have twenty phone entries each pointing at a template. If you serve agents across different networks, expect to deal with NAT traversal, since WebRTC has to find a working path for audio when the agent sits behind a home router that hides their real address. Once the entry registers, the agent works the campaign exactly like any other phone type, and the screen behaves identically whether the audio is a hardphone or a browser tab.

For background on how browser and external phones fit into a campaign, read the pillar on VICIdial remote agents. The companion post on what ViciPhone needs from Asterisk and SSL goes deeper on the certificate and version requirements. If you would rather skip the cert and Asterisk legwork entirely, our managed plans ship a fully provisioned box with valid certificates already in place.