---
title: IVRs
summary: 'An IVR (Interactive Voice Response) is the phone menu callers hear before reaching a person.'
section: features
tags:
  - crud
  - telephony
  - routing
  - ivr
updated: '2026-08-12'
related_forms:
  - ivr_steps
  - smart_ivr_entries
---

> An **IVR** (Interactive Voice Response) is the phone menu callers hear before reaching a person. *"Press 1 for sales, 2 for support, 3 for accounts."* You record the announcement, map each key to a destination, and the IVR plays, listens, and routes.

## Overview

An IVR makes one phone number do many things: the caller chooses their own destination by pressing a digit. A key can point to another IVR for nested menus, or to a call flow for routing.

## What you configure

You record an announcement, map keys to destinations, and pick a default action for any key you have not mapped (or no key at all). When the caller presses an unmapped key or nothing, the default action applies:

| Default action | What it does |
|---|---|
| **Hangup** | End the call. Rare - only for silent callers you want dropped. |
| **Repeat** | Play the announcement again. The usual choice. |
| **Execute Default Step** | Follow whatever the *Default* row in the key mapping points at. |

The key mapping has 13 rows: *Default* (used by *Execute Default Step*) plus the 12 keys 0 through 9, `*`, and `#`. Each row picks a target type (IVR or call flow) and a target. A row set to *IVR* points to another menu, enabling multi-level phone trees. Keep nesting shallow - two or three levels at most.

![The IVR key mapping, showing the Default row followed by one row per key](ivrs-images/key-mapping.png)

> [!IMPORTANT]
> The key mapping section only appears when editing a saved IVR. To map keys, create the IVR first, then click in to edit it.

> [!CAUTION]
> Deleting an IVR referenced from a call flow IVR step or another IVR's key mapping breaks those references silently. Check the IVR's **Usage** tab before deleting.

## How to build a phone menu

1. Create the destinations first. A key can only point at a [call flow](call_flows.md) or another IVR, so those have to exist before there is anything to map to.
2. Record the [announcement](announcements.md) that reads the menu out, naming the options in the order the keys are numbered.
3. Create the IVR with that announcement and **save it**. The key mapping does not appear on a new IVR, so a first pass will not show it.
4. Re-open the saved IVR and map the keys. Thirteen rows: *Default*, plus the twelve keys 0 through 9, `*` and `#`. Leave unused keys unmapped.
5. Pick the default action for unmapped keys and silent callers. *Repeat* is the usual choice.
6. Route callers in: a [phone number](phone_numbers.md) in Call Flow mode, pointing at a flow with an *IVR* step.
7. Test every key you mapped, then test pressing nothing at all.
8. Before deleting or re-pointing this IVR later, check its **Usage** tab. Call flow IVR steps and other IVRs' key mappings break silently.

## See also

- [Call flows](call_flows.md) - the *IVR* step that funnels calls into an IVR, and what the IVR keys route into.
- [Announcements](announcements.md) - the sound files the IVR plays.
- [Phone numbers](phone_numbers.md) - the DIDs that often lead to an IVR via their Call Flow handling mode.
- [Queues](queues.md) - common destination for an IVR key.

```yaml fields
name:
  label: Name
  api: name
  tab: General
  hint: 'A descriptive name for this IVR menu, shown in lists and when selecting an IVR in call flow configurations.'
comment:
  label: Comment
  api: comment
  tab: General
  hint: 'An optional internal note about this IVR. You can edit this directly from the list view.'
announcement:
  label: Announcement
  api: announcement
  tab: General
  hint: 'The sound file played to callers when they reach this IVR. Only sound files of type Announcement can be selected.'
announcement_language:
  label: Language
  tab: General
  hint: 'Which language variant of the announcement to play. Auto plays the language detected or inherited earlier in the call, falling back to the default announcement; pick a language to always play that variant.'
default_action:
  label: 'Default action'
  api: default_action
  tab: General
  hint: 'What happens when a caller presses an unmapped key or no key at all. Options are Hangup, Repeat, or Execute Default Step.'
steps:
  label: Steps
  tab: General
  hint: 'The key-to-destination mappings for this IVR. Only available when editing an existing IVR.'
enable_smart_ivr:
  label: 'Smart IVR'
  tab: General
  hint: 'Route callers through the AI voice assistant instead of key-press menus.'
smart_ivr_entries:
  label: 'Smart IVR announcements'
  tab: General
  hint: 'The announcements the assistant plays, one per announcement type (greeting, hold, transfer, hangup) and language.'
```