Onyx VoiceDocumentation
All chapters

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

SoftphoneWhereHow it signs inEncrypted
Browser softphoneThe user portal, in any modern browserThe person's portal sign-inAlways
Onyx Softphone for WindowsWindows 10 (1809) and 11, 64-bitThe person's portal sign-inAlways
Onyx Softphone for AndroidAndroid 10 and laterThe person's portal sign-inAlways
Onyx Softphone for iPhoneIn development
Any other SIP appZoiper, Linphone and the likeA SIP username and password you give outWhen you turn it on

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:

BadgeMeaning
ReadyRegistered: calls can be made and received.
Connecting...Opening the connection to the server.
OfflineThe connection to the server dropped.
Not registeredConnected but not signed in to the phone system.
Sign-in failedThe phone system refused the account. The page tries again a few times, then shows the reason.
UnavailableThe softphone could not start. A message says why.

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.

Setting up the app with a setup code

The quickest way to give someone the Onyx Softphone is a setup code: the app connects without their password, and two-factor sign-in does not get in the way. The person needs an extension with a portal sign-in (see extensions).

An administrator makes one on Sign-in accounts (click Phone app on the person's row) or on the extension's page (User portal card, Set up the phone app). People make their own on their Sign-in and security page (Set up a phone or computer), for example to add the app on their mobile phone.

The console then shows:

  • a QR code. Scanned with a mobile phone's camera, it opens the setup page on the server, which offers the app download and an Open in Onyx Softphone button;
  • the link to the same page, to send by chat or open on the computer that gets the app;
  • the Server and Setup code (like K7QM-4XTR-9WCB-H2NP) to type into the app under Use a setup code.

Leave E-mail it to ... ticked and the person gets all of it by e-mail, the QR code attached, with download links for Windows and Android. The e-mail goes out through the server's mail settings (see settings); if it cannot be sent, the console says why and the details can still be copied with Copy setup details.

A setup code works once, for one app, for 7 days. The codes not used yet are listed under the button with Cancel; a new password cancels them all. Five can wait at once per person. The app that uses a code gets its own sign-in, listed under Apps signed in. Setup codes need Onyx Softphone for Windows 0.1.9 or Android 0.1.5 or later; older versions sign in with the e-mail address and password.

The setup page and the download links are on the server's own address (its name under certificates, else the address the console was opened with), so the phone must reach the server there. The download links fetch the newest app from the public Onyx update feeds.

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.

With a setup code instead (see above): open the setup link and click Open in Onyx Softphone, or click Use a setup code on the sign-in page, paste the link or type the server and code, and click Connect.

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.

If the person has two-factor sign-in turned on, the app then asks for the Code from your authenticator app (a recovery code works too) and Verify; Back to the password starts over. Versions up to 0.1.6 cannot take the code.

After signing in, the app does not keep the password: it gets a sign-in of its own from the server (see Apps signed in) and uses that whenever it has to sign in again. Older versions kept the password; they move to their own sign-in by themselves once the server offers it.

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, or with a setup code: scan the QR code with the camera and tap Open in Onyx Softphone, or tap Use a setup code in the app.

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).

If the person has two-factor sign-in turned on, the app then asks for the Code from your authenticator app (a recovery code works too) and Verify; Back to the password starts over. Versions up to 0.1.2 cannot take the code. Like the Windows app, it then keeps a sign-in of its own instead of the password (see Apps signed in).

Apps signed in

An Onyx Softphone app signs in once with the person's portal sign-in (and two-factor code) or a setup code, then keeps a sign-in of its own: a long random token that only that app knows and the server keeps only a fingerprint of. The app uses it whenever the server's day-long session runs out, so it keeps ringing without storing the password, and two-factor sign-in does not get in its way.

Each app is listed with its name (for example "Onyx Softphone on FRONT-DESK"), the kind of device, when it was last used and from which address:

  • The person sees their own under Apps signed in on the portal's Sign-in and security (see user-portal), and an administrator on their console account page. Remove signs that app out.
  • An administrator sees anyone's: on Sign-in accounts, click Phone app on the person's row (see console). Use it for a lost or handed-over laptop or phone, and to set up a new one with a setup code.

A removed app shows the person's sign-in page again with "This app's sign-in was removed". A new password (changed by the person or given by an administrator) removes all of the person's apps. A disabled account, or a disabled tenant, stops its apps from signing in until it is enabled again. Signing out of an app removes its own sign-in. An account can have at most 20 apps signed in.

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.