Docs / Phone system

Extensions and users

An extension is a person's number inside the company: their phones ring on it, it has a voicemail box, and it carries the caller ID they call out with. This chapter covers creating extensions, their settings, the phones and softphones that sign in to them (devices), SIP usernames and passwords, and giving the person a sign-in for the user portal.

The Extensions & numbers page

Extensions & numbers lists every number people can dial inside the tenant. Tabs filter it by kind: Everything, Extensions, Ring groups, Queues, Conference rooms, Auto attendants, Business hours and Paging. Each row shows the number, the name (and e-mail for people), the kind, how many of the person's phones are online, and a short line on what the number does. Click a row to open it.

The search box at the top of the console (Find an extension, name or number...) opens this page filtered to what you typed.

Every number in a tenant is unique, whatever it rings: if 101 is an extension, no ring group or menu can also be 101. Numbers are 2 to 8 digits. The call parking number 700 and its slots 701 to 720 are taken in every tenant.

Besides people, the same page creates the other kinds of number. They are described in their own chapters:

Creating an extension

1. Open Extensions & numbers and click Add. The Add a number form opens with Extension selected.
2. Number: what people dial. The form suggests the next free number from 101.
3. Name: the person's name, for example Alice Jones. It is shown on phones when they call.
4. E-mail: optional; voicemail arrives here as an attachment, and it becomes the default for their portal sign-in.
5. Click Create extension.

A box appears with the extension's first phone account and its voicemail PIN:

• SIP server, Username and Password for the phone. The username is acme_101; the password is 24 random characters.
• The voicemail PIN, 6 random digits.

Click Copy phone settings to copy the three phone settings, then Open extension to set it up further, Add another for the next person, or Done. You can show the password again later, so nothing is lost if you close the box.

A new extension has voicemail on, rings for 25 seconds before voicemail, and has one SIP phone account. If the number is already used you see "Extension 101 already exists in acme".

Extension settings

Open the extension from the list. The top shows whether any of its phones are online, its call handling (ringing, forwarded or do not disturb), whether voicemail is on, and the ring groups and queues it belongs to.

The Person and voicemail card:

Click Save. Calls use the new settings within a second.

A voicemail PIN needs at least 4 digits and cannot be a run such as 1111 or a sequence such as 1234, the PINs toll fraudsters try first. Caller ID numbers are 3 to 15 digits with an optional +. How the outbound, emergency, route and main numbers combine is explained in Caller ID.

The Call handling card holds Do not disturb and the three forwarding targets: Forward every call to, Forward when busy to and Forward when not answered to, then Save call handling. The person can change the same settings from the phone and the portal; see Do not disturb and Call forwarding.

Phones and other devices

A device is one sign-in to the phone system: a desk phone, a softphone app, the browser softphone or a DECT handset. An extension can have several, and all of them ring together when someone calls it. Each device has its own SIP username and password, so you can replace one phone without touching the others.

The Phones card of the extension lists its devices with their Status (Online or Offline) and Where they are registered from (address and the phone's own model string). One SIP username can be registered from up to three places at once; a fourth registration replaces the oldest.

A removed device's number is reused: delete acme_101_2 and the next phone added becomes acme_101_2 again.

Desk phones that set themselves up, DECT handsets and their keys are covered in Desk phones; the browser softphone and the Onyx Softphone apps in Softphones.

Adding a phone by hand

Use this for any SIP phone or app that Onyx Voice does not set up for you (Zoiper, Linphone, an unsupported desk phone).

1. Open the extension and click Add a phone in the Phones card.
2. A box shows the SIP server, Username and Password. Click Copy phone settings.
3. In the phone, create a SIP account with:
   • server or registrar: the SIP server shown, for example 10.0.0.20 on the office network or pbx.example.com from outside;
   • username and authentication ID: the username shown, for example acme_101_2;
   • password: the password shown;
   • port 5060 over UDP or TCP.
4. Save. Within a few seconds the device shows Online.

If it stays Offline: check the password (copy it, do not retype it), that the phone can reach the server's address, and that the server's firewall allows SIP from the phone's network. Repeated wrong passwords make the intrusion prevention block the phone's address; see Security and Troubleshooting.

Showing or changing a SIP password

• Show settings shows the server, username and password of a device again.
• New password (click it twice) makes a new random password. The phone is signed out until you enter the new password in it. Phones set up by Desk phones pick the new password up at their next settings fetch.

From the command line: onyx device show acme_101 and onyx device secret acme_101.

Encrypted calls

Click Encrypt calls next to a device to make it register over SIP TLS (port 5061) and encrypt its audio (SRTP). From then on the engine refuses calls with unencrypted audio from that device. Plain calls turns it back.

• A phone set up by hand must be set the same way: transport TLS, port 5061, SRTP required.
• A desk phone set up by Desk phones gets the settings at its next settings fetch. If Onyx Voice cannot set up that model for encryption, the console says so; configure TLS and SRTP on the phone yourself and add it as a SIP phone instead.
• The browser softphone always encrypts its calls, so it has no button.

The server's certificate and SIP TLS are covered in Names and certificates and Security.

Hot desks

Make hot desk turns a device into a shared desk phone that anyone can log in to with *55; Normal phone turns it back. See Hot desking.

Removing a device

Click Remove (twice). The device's username stops working at once.

Giving the person a portal sign-in

The user portal at https://pbx.example.com/portal/ is where people listen to voicemail, see their calls, change forwarding and call from the browser.

1. Open the extension and find the User portal card.
2. Check the e-mail address (it starts as the extension's E-mail).
3. Click Create portal sign-in.
4. The card shows the Address, E-mail and Password. Click Copy sign-in details and pass them on. The password is not shown again; the person can change it after signing in.

From then on the card shows who signs in, when they last did, and the portal address. Reset a forgotten password on Sign-in accounts with New password. Each extension has one portal account.

An account created on Sign-in accounts with the role Phone user is not linked to any extension, and the portal tells that person to ask their administrator. Create portal sign-ins from the extension's User portal card, or link them on the command line.

From the command line (the role must be given, because an account with a tenant defaults to tenant administrator):

onyx user add [email protected] --name "Alice Jones" --role User --tenant acme --extension 101

It prints a generated password. What people can do in the portal is in The user portal.

Taking an extension out of service

Clear Extension in service and click Save. The extension's phones can no longer register, calls to its number fail, and its voicemail box cannot be reached; its settings and messages are kept. Tick it again to bring it back.

Deleting an extension

1. Open the extension.
2. Click Delete extension, then click again to confirm.

Its devices are deleted with it, so the phones stop working at once. A portal account linked to it stays but is no longer linked to anything; delete it on Sign-in accounts if it is no longer needed.

Before deleting, take the number out of ring groups, queues, paging groups, menus and phone numbers that send calls to it. Calls sent to a number that no longer exists end, and the engine writes a warning to its log. Voicemail messages stay on the server's disk; a new extension with the same number later would find them.

From the command line

onyx ext list acme
onyx ext add acme 101 --name "Alice Jones" --email [email protected]
onyx ext show acme 101
onyx ext set acme 101 --callerid +16125550101 --emergency-cid +16125550101 --ring 30 --pin 482913
onyx ext set acme 101 --vm off --record always --enabled on
onyx ext calls acme 101 --dnd on
onyx ext delete acme 101

onyx device list acme 101
onyx device add acme 101 --kind sip --label "Kitchen phone"
onyx device add acme 101 --kind webrtc
onyx device secret acme_101_2
onyx device secure acme acme_101_2 on
onyx device delete acme_101_2

onyx ext add prints the voicemail PIN and the first device's settings. See Command line (onyx) for every option.