# Voice Menu (IVR)

An Interactive Voice Response (IVR) system acts as your virtual receptionist, automatically greeting callers and guiding them to the right department or person. Think of common scenarios like:

- "Press 1 for Sales, 2 for Support"
- "For English, press 1. Para español, presione 2"

![Voice Menu module](/docs/phone-system-guide/modules/img/voice-menu-module.jpg)

## How It Works {#how-it-works}

When someone calls, the IVR:
1. Plays your custom greeting
2. Presents menu options
3. Routes the call based on the caller's keypad input

This automation helps:
- Direct calls efficiently
- Reduce wait times
- Provide 24/7 service
- Handle multiple calls simultaneously

:::note[DTMF Compatibility]
The Voice Menu module relies on DTMF tones for caller input. While the FlyNumber system fully supports DTMF, if you're experiencing issues with button presses when receiving calls from third-party services, check our [DTMF troubleshooting guide](../technical-specs.md#dtmf-support-third-party-integration) for integration requirements.
:::

## Setting It Up {#setting-it-up}

![Voice Menu creation interface](/docs/phone-system-guide/modules/img/ive-create.png)

### Basic Configuration {#basic-configuration}

1. **Name**: Give your IVR a descriptive name (e.g., "Main Menu" or "After Hours")

2. **Audio Message**: Select a pre-recorded greeting that explains the menu options, or pick **Create Audio File** in the dropdown to generate one from typed text
   - Supported formats: .mp3, .m4a, .wav, .flac, .ogg (up to 14 MB per file)
   - Can record directly or use existing audio files
   - Pro tip: Keep messages clear and concise

3. **Timeout Settings**: 
   - Set how long to wait for caller input (1 second to 2 minutes); the timer starts once the greeting has finished playing
   - Define how many times to replay the menu (1 to 11 times)

![Voice Menu timeout settings](/docs/phone-system-guide/modules/img/ivr-timeout.png)

### Creating Connections {#creating-connections}

![Voice Menu connection types](/docs/phone-system-guide/modules/img/ivr-connect.png)

When connecting your IVR to other modules, you'll need to specify the connection type:

1. **Extension**: Routes calls based on the number pressed
   - Example: "Press 100 for Sales" connects to the [Sales Ring Group](./ring-group.md)
   - Each extension must be unique
   - To change an extension later, click the number shown on the cable

![Voice Menu extension configuration](/docs/phone-system-guide/modules/img/ivr-extension.png)

2. **IVR invalid selection**: Handles incorrect inputs
   - Plays an error message
   - Can redirect to a live operator
   - Option to return to main menu

3. **Reached the timeout limit**: Manages when no input is received after the last playback
   - Can forward to a default department
   - Option to play a timeout message
   - Ability to retry or transfer

## Basic Example {#basic-example}

![Basic Voice Menu setup example](/docs/phone-system-guide/modules/img/ivr-example-basic.jpg)

This simple setup shows:
- Incoming calls from a [phone number](./phone-number.md)
- Two department options (Sales and Support)
- Error handling for invalid inputs
- Timeout handling for no response

## Advanced Example {#advanced-example}

![Advanced Voice Menu setup example](/docs/phone-system-guide/modules/img/ivr-example-advanced.jpg)

This advanced configuration demonstrates:
- Multiple menu levels
- Error message playback
- Return to menu options
- Integration with [Ring Groups](./ring-group.md) and [Internal Numbers](./internal-number.md)

## Managing Error Handling {#error-handling}

When a caller interacts with your Voice Menu, there are two common scenarios that require proper handling:

1. **Timeout**: When a caller doesn't press any key within the set time limit
2. **Invalid Selection**: When a caller presses a key that doesn't correspond to any defined extension

You can configure both cases by dragging cables from the right side of the Voice Menu module:

![Voice Menu timeout and invalid key handling](/docs/phone-system-guide/modules/img/timeout-example.png)

In the example above:
- Cables labeled with "t" handle timeout scenarios
- Cables labeled with "i" handle invalid key presses
- Cables labeled with numbers (1, 2, 9) handle valid menu options

Both timeout and invalid selection connections typically lead to an Audio Playback module that can:
1. Inform the caller of their error ("Sorry, I didn't catch that" or "That's not a valid option")
2. Direct them back to the Voice Menu to try again
3. Connect them to a default destination (like a receptionist) for assistance

:::tip[Best Practices]
- Keep menu options simple (4-5 choices maximum)
- List the most common options first
- Provide a way to reach a live person
- Only use digits (0-9) for menu options, not special characters (* or #)
- Test all paths to ensure proper routing
:::

:::note
Remember to update your IVR message whenever you change the menu structure or extension numbers. This ensures callers always receive accurate instructions.
:::