Docs / Devices

Softphones

A softphone is a phone in software: in a web browser, on a computer or on a mobile phone. Onyx Voice has a softphone built into the user portal, the Onyx Softphone apps, and it works with any other SIP softphone. This chapter covers each, how a person connects them, and how their calls are encrypted.

Which softphone to use

The browser softphone and the Onyx Softphone apps share one account per extension, set up by Onyx the first time it is used. For any other SIP app you add a device to the extension and give the person its settings.

Every softphone rings together with the person's desk phone and other devices: an extension rings all of its phones at once.

The browser softphone

Every person with a portal sign-in has a softphone at the top of the portal (see user-portal). There is nothing to install and nothing for the administrator to set up: the first time the person opens the portal, Onyx creates the extension's Browser softphone device (labelled "Browser") and the page signs in with it. An administrator can also add it in advance with Add browser softphone on the extension's page (see extensions). An extension has at most one.

To make a call:

1. Open https://pbx.example.com/portal/ and sign in. The softphone's badge goes from Connecting... to Ready.
2. Type a number or extension in Number or extension, or use the dial pad, and press Call (or Enter). The first time, the browser asks for the microphone: allow it.
3. During the call: Mute, Hold, the dial pad sends key presses (for menus and voicemail), and Hang up ends it.

To transfer a call, type the number to transfer to and press Transfer. The caller is sent there straight away (a blind transfer) and your part of the call ends.

When a call comes in, the softphone rings and shows who is calling with Answer and Decline. The browser softphone takes one call at a time: a second call while you are on one is turned away from the browser, and your other phones still ring for it. Browsers only allow sound after you have clicked on the page, so the ring can be silent in a tab you opened and never touched; the call still shows.

The softphone is registered only while the portal page is open. Close the tab and the browser stops ringing; keep a tab open (it can be in the background) to take calls.

The badge tells you its state:

How it connects

The browser softphone needs no ports of its own. Its signalling goes over a secure WebSocket through the server's HTTPS address (port 443), and only for signed-in people. Its audio uses WebRTC: it is always encrypted (DTLS-SRTP) and goes straight to the server's audio ports, like a desk phone's. Audio is G.722 (wideband) or G.711 µ-law.

For the softphone to work:

• The server's certificate should be one the browser trusts (Let's Encrypt or your own, see certificates). With a self-signed certificate the browser warns before it opens the portal.
• People outside the office need to reach the server's HTTPS port and its audio ports, and the server must know its public address (see network). If the STUN server setting is filled in, the browser uses it too, to find its own public address.

Onyx Softphone for Windows

Onyx Softphone for Windows is a tray app with a dial pad, caller ID and missed calls, and it updates itself from a signed feed. Download it from the Download section of onyxvoice.net (downloads ask for a user name and password; the site says how to ask for access). There is an installer for one computer and an MSI for deployment across many.

To connect it:

1. Start Onyx Softphone.
2. Enter the Phone system address (for example pbx.example.com), the person's E-mail address and Password: the same sign-in as the user portal.
3. Click Sign in.

If the server has a self-signed certificate, the app shows the certificate and asks whether to trust it. Accept it only if it is your server's.

The app uses the same account as the browser softphone, so the app and an open portal tab ring together. One account can be signed in from up to three places at once (for example the portal, the Windows app and the Android app); a fourth replaces the oldest.

Onyx Softphone for Android

Onyx Softphone for Android rings like a normal call, on the phone's own call screen. It is coming soon: the Download section of onyxvoice.net will offer the APK. To install it, allow installs from your browser when Android asks.

The person signs in the same way as on Windows: Phone system address, E-mail and Password.

Onyx Softphone for iPhone

An iPhone app is in development. Until it is available, people on an iPhone can use another SIP app (see below).

The Onyx Softphone apps do not ask for a two-factor code yet. A person who has turned on two-factor sign-in for their portal account cannot sign in to the apps; they can still use the browser softphone in the portal, or another SIP app with a device account.

Other SIP apps

Any standard SIP softphone (Zoiper, Linphone, a softphone built into a headset's software) works with Onyx Voice as an ordinary SIP device. People cannot get these settings from the portal themselves; an administrator adds the device and passes the settings on.

To set one up:

1. In the console, open Extensions & numbers and the person's extension.
2. Under Phones, click Add a phone. Onyx creates a SIP phone device and shows its settings: SIP server, Username and Password.
3. Click Copy phone settings and give them to the person, or type them into the app yourself.
4. In the app, create a SIP account with that server, username and password (the username also goes into "authentication user" where the app asks for one). Leave the domain as the SIP server.

The device shows Online on the extension's page once the app has registered, with its address and the app's name under Where. Show settings shows the details again; New password makes a new one and signs the app out until it gets it. Each device can be registered from up to three places at once.

SIP server shows the server's own address first, with its public address (or its name, when no public address is set) in brackets: use the first inside the office and the second from outside. An app outside the office needs the SIP and audio ports reachable (see network). Failed sign-ins count towards intrusion prevention, so an app with a mistyped password can get the person's address blocked for a while, unless the address is on the never-block list (see security).

Encrypted calls for SIP apps

To encrypt a SIP app's calls:

1. On the extension's page, click Encrypt calls next to the device.
2. In the app, set the account's transport to TLS, the port to the SIP TLS port (5061 by default), and audio encryption to SRTP (SDES) as required.

From then on the server only accepts encrypted audio from that device, so its calls fail until the app is set the same way. The app checks the server's certificate: with Let's Encrypt or your own trusted certificate it works as it is; with a self-signed certificate most apps need to be told to accept it. Plain calls turns encryption off again.

The browser softphone and the Onyx Softphone apps need none of this: their calls are always encrypted.