> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IVR Menu Navigation

> Let an outbound agent work its way through a phone menu to reach a person or a department

Many business numbers answer with an automated menu: *"Press 1 for sales, 2 for support…"*. With **IVR Menu Navigation** on, an outbound agent that reaches such a menu presses keys or speaks keywords to get to the person or department you want, instead of hanging up.

Navigation starts from the [Answering Machine Detection](/functions/answering-machine-detection) verdict, so it **requires AMD to be on**. Switching AMD off switches navigation off with it, and the API refuses a request that would leave navigation on while AMD is off.

## Turning it on

In the Dashboard or the Connect App, open an outbound agent's settings and find **IVR Menu Navigation**, directly under Answering Machine Detection. Through the API, set `ivrNavigation` on [Create Agent](/api-reference/agents/create) or [Update Agent](/api-reference/agents/update): `true` for the defaults, an object to tune it, `false` to turn it off.

```json theme={null}
{
  "amdConfig": true,
  "ivrNavigation": {
    "enabled": true,
    "target_intent": "reach_department",
    "target_department": "billing"
  }
}
```

## Settings

| Setting | API key | Default | What it does |
| - | - | - | - |
| IVR Menu Navigation | `enabled` | `false` | Turns navigation on |
| What to reach | `target_intent` | `reach_human` | `reach_human` (any live person), `reach_department` (a named department), or `custom` (a goal you describe) |
| Department to reach / Describe the goal | `target_department` | — | The department name for `reach_department`, or the goal for `custom` (for example *"the pharmacy refill line"*) |
| Spoken keywords | `spoken_keywords` | representative, agent, operator | Words the agent says on speech-driven menus. Up to 20 |
| Max key-presses | `max_attempts` | `3` | Key-presses before giving up. At most 10 |
| Max navigation time (seconds) | `max_duration_ms` | 45 s | Wall-clock cap on the whole navigation. At most 10 minutes |
| If navigation fails | `fallback_action` | `press_zero` | What to do when a limit is hit: `press_zero` (try the operator key), `hang_up`, or `wait_for_human` (stay quiet on the line for a person) |
| Max hold time (seconds) | `hold_max_wait_ms` | 3 min | Once the agent detects hold music or a repeating hold message, how long it waits for a person before giving up. At most 30 minutes |

The agent stays silent while it navigates, so every one of these limits is billed, silent call time. Set them a little above what the menus you call actually need.

## How the call ends

The outcome is recorded on the call as `ivr_navigation_outcome`, shown next to the **IVR menu** badge in the Outbound Calls report, and sent on the [result webhook](/api-reference/outbound-calls/overview#the-result-webhook).

| Outcome | Meaning |
| - | - |
| `reached_human` | A person came on the line; the conversation continued normally |
| `reached_department` | The target department answered |
| `failed_max_attempts` | The key-press limit was hit and the fallback ran |
| `failed_timeout` | The navigation time limit was hit and the fallback ran |
| `hold_timeout` | The agent waited on hold for the maximum time without reaching anyone |
| `disconnected` | The far end hung up during navigation |

When navigation did not run on a call, the field is `null`.

## Scripting a known menu per call

For a number you call often, you can skip the live navigation and press a fixed sequence of keys. Pass `ivr_map` when you [trigger the call](/api-reference/outbound-calls/create): an ordered list of steps that each wait for a menu phrase (`wait_for`) or a fixed delay (`wait_ms`), then press `send_dtmf`.

```json theme={null}
{
  "to_number": "+18135551234",
  "ivr_map": [
    { "wait_for": "billing", "send_dtmf": "2" },
    { "wait_ms": 3000, "send_dtmf": "0" }
  ]
}
```

Up to 20 steps; each `wait_ms` is at most 60 seconds, `send_dtmf` is 1–32 digits (`0-9`, `*`, `#`), and the whole script must fit in 10 minutes including the presses. A script still needs AMD on for that call, since it is the menu verdict that starts it. A retry of the call reuses the same script.

You can also override the agent's navigation settings for one call with `ivr_navigation` on the same request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.