Onyx VoiceDocumentation
All chapters

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. Make it from text on this page (below), or record it on a computer and upload it. Onyx Voice does not record prompts over the phone yet.

Making a prompt from text

  1. Open Prompts & hold music and find Make a prompt from text.
  2. Name it, type What it says, and pick a Voice.
  3. Set the Speed (from 0.70× slower to 1.30× faster; Normal is the voice's own pace) and the Pause at commas: Short (0.3 s), the default, Long (0.6 s), Very long (1 s), or Voice's own for the voice's usual short breath. Semicolons and colons pause the same way; the comma in a number like 1,000 does not.
  4. Click Listen to hear it; change the words, voice, speed or pause until it sounds right. Commas are the easy way to slow a menu down where callers need a moment: "For sales, press 1. For support, press 2."
  5. Click Save prompt. It is converted for phones like an upload and appears in the list as "made from text".

To change a prompt made from text, click Edit text next to it, change the words, voice, speed or pause and click Save new version. It stays the same prompt, so every menu and queue that plays it plays the new version at once. The prompt keeps its speed and pause, so the next edit starts from them.

Voices come from two places:

  • On this server: six voices (US and British English, female and male), made by the server itself with the onyx-voice-speech package. Nothing leaves the server and nothing is paid per prompt. A greeting takes a few seconds to make.
  • A cloud voice service (optional): OpenAI, ElevenLabs or Azure, with your own account and API key, set up under Server settings › Voices (Server settings reference). The text is sent to that service to be spoken; the result is stored on the server like any other prompt.

Uploading a recording

  1. Open Prompts & hold music.
  2. In Upload audio, choose the File: WAV, MP3, FLAC or OGG, up to 50 MB.
  3. Name it, for example Main greeting. Empty takes the file name.
  4. Leave Use as on Prompt (menus, announcements).
  5. 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

  1. Upload the greeting first (see Prompts).
  2. Open Auto attendants in the menu and click Add. The form suggests a number from 800.
  3. Enter the Name, for example Main menu.
  4. Greeting: the prompt to play, or No greeting (silence). Not sure what it should say? Add the menu options first, then under What the greeting says (below the options) click Write the greeting for me. Onyx Voice writes it from the menu as it is on screen: the company name, each key and who or what it reaches, direct dialling and "stay on the line" when the menu repeats. A menu that a business hours number sends calls to only while closed gets the after-hours version, with the opening hours read out. Edit the text, pick a voice, set the Speed and Pause at commas (as in Making a prompt from text), click Listen, then Use as the greeting: the greeting is made and chosen for this menu (save the auto attendant to keep it). If the menu's greeting was itself made from text, it is made again in place. You can also record the text yourself and upload it.
  5. 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.
  6. Callers may also dial an extension number directly: on by default.
  7. Wait for a key (seconds): how long the menu waits after the greeting, 1 to 60 (default 5).
  8. Tries: how often the menu plays before giving up, 1 to 10 (default 3).
  9. When nobody presses a key and When a wrong key is pressed: where the call goes after the last try.
  10. 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.

Asking for a name

Callers can say who they want instead of knowing an extension number. Choose Ask for a name as the destination of a key ("to reach someone by name, press 9"), or as When nobody presses a key, so a caller who just waits is asked.

The menu then says "Please say the name of the person or department you are calling", listens, and connects the caller ("Connecting you to Heidi Larson"). Callers can say a full name, a first or last name alone, or the name of a ring group or call queue ("Sales", "Support"), with words around it ("I'd like to speak to Heidi, please"). They can talk over the question.

  • When the name is not clear, for example "Mark" with two Marks in the directory, the menu asks again once, then says "Sorry, I couldn't find that name" and plays the menu again.
  • A key pressed while the menu listens counts as that menu key.
  • With When nobody presses a key, the menu asks for a name as often as its Tries allow, then says goodbye.

Who can be asked for by name: every extension, ring group and call queue that is switched on, by the name it has on Extensions & numbers. Give them the names callers use. Two numbers with the same name answer to the first one.

Speech recognition runs on this server, with the same speech model as voicemail transcripts; nothing is sent elsewhere. Phone audio is understood in about half a second. The questions are spoken in the server's default voice (Making a prompt from text), made ahead of time in the background, so the first call after a change may hear "Connecting you now" instead of the name. Asking for a name needs the onyx-voice-speech package (for the questions) and works in English.

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 others on holidays and during breaks. Ring groups, queues and auto attendants can also follow its hours themselves (see Office hours on ring groups, queues and menus).

Creating business hours

  1. On Extensions & numbers, click Add and choose Business hours. The form suggests a number from 500.
  2. Enter the Name, for example Office hours.
  3. Open hours: one line per set of days, for example:
    mon-fri 08:00-17:00
    sat 09:00-12:00
  4. Holidays (closed all day): one line per day, for example:
    2026-11-26 Thanksgiving
    12-25 Christmas
  5. Breaks (closed for a while), optional: one line per break, in the same format as the open hours, for example mon-fri 12:00-13:00 for a lunch closing.
  6. Choose When open, When closed, On holidays and During breaks (both Same as closed by default).
  7. 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 either write two lines (mon-fri 08:00-12:00 and mon-fri 13:00-17:00) or keep one line and add the break under Breaks, which can send calls somewhere of its own.
  • 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 breaks, 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. Breaks: --break "mon-fri 12:00-13:00" (repeat for more) and --break-dest <destination>.

Office hours on ring groups, queues and menus

Instead of putting business hours in front of every ring group, a ring group, queue or auto attendant can follow business hours itself. Callers who reach it while the business hours are closed (or on a holiday, or during a break) go elsewhere instead of ringing; while open it works as before. A number that follows no business hours takes calls at any hour.

  1. Open the ring group, queue or auto attendant.
  2. On the Office hours card choose the business hours under Follow business hours.
  3. Choose where calls go While closed, On holidays and During breaks (the last two are Same as closed by default).
  4. Click Save office hours.

Forcing the business hours open or closed (*27/*28, or the Right now card) applies to everything that follows them. From the command line:

onyx hours acme 600 --follow 500 --closed vm:101 --holiday 801
onyx hours acme 600 --off

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

  1. Open Prompts & hold music.
  2. In Upload audio, choose the File and give it a Name.
  3. Set Use as to Hold music.
  4. 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.
  5. Click Upload. Repeat for every track of the class.

Choosing the tenant's hold music

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

The tenant's music plays to callers on hold, to parked callers, to callers waiting in its call queues, and to people alone in its conference rooms or waiting for the moderator. 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.