Docs / Phone system

Auto attendants, opening hours and prompts

An auto attendant answers calls with a recorded menu ("press 1 for sales, 2 for support"). Business hours numbers (time conditions) send calls one way while the office is open and another way when it is closed or on a holiday. Both use recordings you upload on Prompts & hold music, which is also where the tenant's hold music is chosen. This chapter covers all three.

A typical main number: the phone number (DID) goes to a business hours number; while open, that sends calls to the auto attendant; while closed, to a voicemail box or an after-hours menu.

Prompts

A prompt is a recording that a menu or a queue plays: a greeting, an announcement, a closed message. Onyx Voice does not record prompts over the phone or make them from text yet, so record them on a computer and upload them.

To upload a prompt:

Open Prompts & hold music.
In Upload audio, choose the File: WAV, MP3, FLAC or OGG, up to 50 MB.
Name it, for example Main greeting. Empty takes the file name.
Leave Use as on Prompt (menus, announcements).
Click Upload.

Onyx Voice converts the file for phones (mono, 8 kHz for ordinary phones and 16 kHz for wideband ones, levelled to the same loudness) and shows its length. If the file cannot be read, the upload says "The audio file could not be converted"; save it again as a plain WAV or MP3 and retry.

The list shows every prompt and hold music track with its length, a player to Listen, and Delete. Names are unique per tenant; uploading a second "Main greeting" is refused, so delete the old one first or use a new name. If you delete a prompt that an auto attendant uses as its greeting, that menu plays silence until you choose another greeting.

Tips: record in a quiet room, keep greetings short, and say the options in the order people need them. Silence at the start of the file is played too.

From the command line: onyx media add acme "Main greeting" greeting.wav, onyx media list acme, onyx media delete acme 12.

Where calls can go

Menus, business hours, ring groups and queues all ask where a call goes next. The list offers:

Hang up;
any number in the tenant's plan under Numbers: an extension, ring group, queue, conference room, paging group, auto attendant or business hours number;
Voicemail of an extension, for extensions with voicemail on. The caller goes straight to the box and hears its unavailable greeting.

An outside number cannot be a destination directly. To send a menu option to a mobile or an answering service, create a ring group whose only member is that outside number and choose the ring group. More on destinations in Destinations.

Auto attendants

Creating an auto attendant

Upload the greeting first (see Prompts).
On Extensions & numbers, click Add and choose Auto attendant. The form suggests a number from 800.
Enter the Name, for example Main menu.
Greeting: the prompt to play, or No greeting (silence).
Menu options: click Add an option for each key. Choose the key (Key 1 to Key 9, Key 0, or the keys * and #) and where it goes.
Callers may also dial an extension number directly: on by default.
Wait for a key (seconds): how long the menu waits after the greeting, 1 to 60 (default 5).
Tries: how often the menu plays before giving up, 1 to 10 (default 3).
When nobody presses a key and When a wrong key is pressed: where the call goes after the last try.
Click Create auto attendant.

Then send calls to it: route a phone number to it (Routing a phone number), or choose it as the "when open" destination of a business hours number.

What callers hear

The menu answers the call and plays the greeting. Callers can press a key at any time during it.

A key with an option goes to its destination.
A key without an option plays "that option is invalid" and starts the menu again.
No key within the wait plays a short "I'm sorry" and starts again.
After the number of Tries, the call goes to When a wrong key is pressed or When nobody presses a key, whichever happened last. Both are Hang up unless you choose otherwise; an operator or a general voicemail box is usually kinder.

With direct dialling on, callers can dial any number in the tenant's plan, not only extensions, so say in the greeting if they may. The menu waits two seconds after the last key, so a caller who presses 1 and then 01 reaches extension 101 rather than option 1. Turn direct dialling off if the menu should only offer its options.

For a second level ("press 3 for billing questions, then..."), create another auto attendant and choose its number as the destination of a key.

Changing an auto attendant

Open its number on Extensions & numbers, change the Settings card and click Save. Calls use the change right away.

From the command line:

onyx ivr add acme 800 --name "Main menu" --greeting "Main greeting" --option 1=600 --option 2=650 --option 0=101 --timeout-dest vm:101 --invalid-dest 101
onyx ivr set acme 800 --name "Main menu" --greeting "Main greeting" --option 1=600 --no-direct-dial
onyx ivr list acme

onyx ivr set replaces the whole menu: options, greeting and settings you leave out go back to their defaults, so give them all again.

Business hours (time conditions)

A business hours number sends each call to one destination while open, another while closed, and optionally a third on holidays.

Creating business hours

On Extensions & numbers, click Add and choose Business hours. The form suggests a number from 500.
Enter the Name, for example Office hours.
Open hours: one line per set of days, for example:
```
mon-fri 08:00-17:00
sat 09:00-12:00
```
Holidays (closed all day): one line per day, for example:
```
2026-11-26 Thanksgiving
12-25 Christmas
```
Choose When open, When closed and On holidays (Same as closed by default).
Click Create business hours.

Writing open hours and holidays

Days are mon, tue, wed, thu, fri, sat, sun; a range such as mon-fri; or a list such as sat,sun.
Times use the 24-hour clock in the tenant's time zone. The end time is when it closes: 08:00-17:00 is closed from 17:00.
A range must end on the same day, after it starts, at 23:59 at the latest. For a lunch break write two lines: mon-fri 08:00-12:00 and mon-fri 13:00-17:00.
A holiday is a date (2026-11-26) for that day only, or month and day (12-25) for every year, followed by an optional name.

Each call is checked in this order: a manual override first, then holidays, then the open hours; outside all of them it is closed. If calls go the wrong way at the edges of the day, check the tenant's time zone (Time zone).

Forcing open or closed

For a snow day, an event or a late night, force the business hours open or closed. The override stays until someone switches it back; it does not end at midnight.

In the console, open the business hours number. The Right now card shows whether it follows the schedule or is forced, with the buttons Follow the schedule, Force open and Force closed.

From any phone of the tenant:

*27 and the number forces it closed, for example *27500;
*28 and the number forces it open, for example *28500;
dialling the same code again returns it to the schedule.

The phone says "activated" or "de-activated". A desk phone key of type Extension (BLF) with the value *27500 lights while it is forced closed and switches it when pressed; one with *28500 does the same for forced open. See Phone keys (BLF) and presence.

From the command line: onyx time override acme 500 closed, open or auto.

Changing business hours

Open the number, change the Settings card and click Save. Overrides stay as they are.

From the command line:

onyx time add acme 500 --name "Office hours" --hours "mon-fri 08:00-17:00" --hours "sat 09:00-12:00" --holiday 12-25=Christmas --open 800 --closed vm:101
onyx time set acme 500 --name "Office hours" --hours "mon-fri 08:00-18:00" --open 800 --closed vm:101 --holiday-dest 801
onyx time list acme

Like onyx ivr set, onyx time set replaces the whole definition, including the holidays.

Hold music

Each tenant chooses what its callers hear on hold: the standard music that comes with Onyx Voice, or tracks it uploaded.

Uploading hold music

Open Prompts & hold music.
In Upload audio, choose the File and give it a Name.
Set Use as to Hold music.
Music class: a group of tracks that play in random order. Keep default unless you want several sets, for example default and holiday. Class names are lowercase letters, digits and dashes.
Click Upload. Repeat for every track of the class.

Choosing the tenant's hold music

In the card Hold music for this tenant, choose Standard music (built in) or Uploaded: and a class.
Click Use.

The tenant's music plays to callers on hold, to callers waiting in its call queues, and to people alone in its conference rooms or waiting for the moderator. Parked calls always hear the standard music. A class appears in the list once it has at least one track; if all its tracks are deleted, the tenant falls back to the standard music.

Only upload music you have the rights to play to callers.

From the command line, onyx media add acme "Spring track 1" track1.mp3 --moh spring uploads a track to the class spring, and onyx tenant set acme --moh spring chooses that class. onyx tenant set acme --moh default goes back to the standard music, so an uploaded class that is itself named default can only be chosen in the console.