Usage
Browser phones and the desktop app
The console carries a phone of its own: a user signs in and calls from the browser. Offhook, the desktop app, is that page in a window with a tray. Both need the console over HTTPS.
What a browser needs
A page may only use a microphone over HTTPS, except on localhost. So the console must be served over HTTPS for the phone to work from anyone's desk: -api-tls-addr 0.0.0.0:8443 (or SIDETONE_API_TLS_ADDR) adds a listener for the API and the console with the server's own certificate. A fresh install has a self-signed one, which works once the browser has been told to accept it; a real one comes by upload or from Let's Encrypt, see Encryption. Users then open https://pbx.example.com:8443/.
The phone signals over SIP on WebSocket, served on the same listener at /sip, and its audio is WebRTC: ICE, DTLS-SRTP, so it is encrypted end to the server whatever the other party of the call is. No STUN or TURN server is needed in the common case, because the server is the public party: audio goes to the server's address on the audio port range like everyone else's, and the same firewall rules apply. A browser out on the internet needs the public address known, which a registering trunk teaches the server, or -external-ip says.
The Phone page
A user signs in to the console with their extension and console password and opens Phone. The page becomes one of their softphones, with credentials of its own that it keeps in the browser (never the console password), registers, and calls with the computer's microphone and speaker: a dial pad, people and recent calls to click, hold, mute, transfer, keys during a call, a choice of microphone, speaker and ringer. Their desk phone rings too, and whichever answers takes the call. Forget this phone removes the softphone again.
It works on any machine that reaches the console over HTTPS, or on the server itself over plain HTTP. Audio is G.711 like every other phone's. Each softphone shows on the Desk phones page as a softphone, where an administrator can remove it; five per user.
Offhook, the desktop app
Offhook is the Phone page in a window of its own, for Windows, Linux and macOS. It adds what a page cannot be: a tray icon, a phone that keeps running when the window is closed, and a judge of the server's certificate. It has no telephony of its own, so updating the server updates the phone.
- Install a release for your system, start it, and give it the server's address:
https://pbx.example.com:8443, say. - If the server has a certificate your computer does not know, the app shows its fingerprint and asks once. Trust it if it is your own server; from then on the app accepts that certificate and no other from that server.
- Sign in with your extension and your console password. Closing the window keeps the phone running in the tray; Quit from the tray hangs up.
Builds are unsigned for now, so Windows and macOS ask you to allow the app the first time.
Other browser softphones
A browser softphone of your own choosing (JsSIP, SIP.js and the like) registers over WebSocket and needs nothing configured on the server: a phone that registers over WebSocket is rung with WebRTC media, a caller that offers it gets it, and the other party of the call can be any ordinary phone or trunk. Give it wss://pbx.example.com:8443/sip (or /, for a client that cannot be given a path), the extension and the SIP password. Tell it not to insist on Opus if it has such a setting. A ws:// or wss:// entry in -sip-listen still works for a client that wants a port of its own.
Networks that block UDP
A browser on a hotel or office network that lets no UDP out, or only TCP 443, cannot reach the server's audio ports and needs a relay: a TURN server. sidetone hands browser phones the servers you list under Settings → Browser phones, with credentials minted for each user at every call. TURN with hairpin sets one up in a minute.