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

# IVR Nodes

> Run a deterministic TTS + DTMF menu at the start of a call — before the LLM activates

> [!WARNING]
>
> IVR nodes are available **only in Pathway agents**. If your agent is set to Basic, Advanced, or Multi-Prompt mode, this feature does not apply.

An **IVR node** lets you add an automated phone menu at the very beginning of a call. The agent speaks a fixed message using text-to-speech, waits for the caller to press a key on their keypad, and routes the call to the next step based on what they pressed — all without starting the AI conversation engine.

This is useful for:

* **Language selection** — "Press 1 for English, press 2 for Hindi"
* **Consent gates** — "Press 1 to continue, press 2 to opt out"
* **Department routing** — "Press 1 for Sales, press 2 for Support"
* **Fixed announcements** — play a message and hang up, or play and continue
* **Pre-qualification** — collect a simple choice before the AI conversation starts

> [!NOTE]
>
> IVR nodes run before any AI or speech recognition. The caller hears a pre-written message and presses a number key. No transcript is created during the IVR phase.

***

## How it works

1. The call connects and the IVR phase starts on the first node (the **starting node**).
2. The agent speaks the message for that node.
3. The caller presses a key (or does nothing).
4. The call routes to the next node based on the key pressed — which can be another IVR node or the start of the AI conversation.
5. Once the call reaches the first AI (LLM) node, the normal voice-agent conversation begins.

> [!WARNING]
>
> Once the AI conversation has started, the call **cannot go back** to an IVR node. IVR nodes are only active at the beginning of the call.

***

## Setting up an IVR node

On the Pathway canvas, add a new node and set its **Node Type** to **IVR**. The configuration panel shows the IVR-specific fields described below.

### Message

The text the agent speaks when this node is entered. You can include call variables using `{{variable_name}}` — for example, `Hello {{customer_name}}, press 1 to continue.`

### Timeout

How many seconds to wait for a key press after the message finishes. Default is 8 seconds. If the caller does not press anything within this time, it counts as "no input."

### Max Retries

How many times the message plays before the call routes to the **No Input** destination. For example, if Max Retries is set to 2, the message plays twice total before routing — once on first entry, once after the first timeout.

### No Input Destination

Where the call goes when the caller does not press any key after all retries are exhausted. This can be the same IVR node (to repeat), a different IVR node, or an AI conversation node.

### Invalid Key Destination

Where the call goes when the caller presses a key that is not in your menu options. You can re-route to the same node to replay the menu, or send them somewhere else.

### Key Options

The routing table — each entry maps one key to the next node:

| Key | Next Node |
| - | - |
| 1 | `english_agent` (AI node) |
| 2 | `hindi_agent` (AI node) |
| 9 | `opt_out` (IVR hangup node) |

You can use keys 0–9. Each key must map to an existing node in your pathway.

***

## Special modes

### Skip Input (announcement node)

Turn this on to speak the message and immediately move to the **No Input Destination** without waiting for a key press. Use this when you want to play a fixed announcement and continue automatically — for example, a legal disclaimer before the conversation.

### Hang Up After Message

Turn this on to speak the message and end the call immediately. Use this as a terminal node — for example, to play "You have opted out. Goodbye." and disconnect.

***

## Message while switching

Like AI nodes, an IVR node can have a **Message while switching** — a short phrase spoken when the call first arrives at this node (not on retries). Use it to fill the brief pause between nodes: *"Please wait while we connect you."*

Set the type to **Static** and write your message. This message plays before the node's main message on the first visit only.

***

## Conditions

After the agent finishes speaking, it can check conditions against the call's pre-loaded variables before waiting for any key press. If a condition matches, the call routes to that node immediately — the caller does not need to press anything.

This is useful when you already know something about the caller from the campaign data or CRM — for example, their preferred language or whether they previously opted out.

> [!NOTE]
>
> Conditions are evaluated **after** the message and **before** any key-press wait. The first condition that matches wins. If no condition matches, the normal key-press menu runs as usual.

### What you can use in conditions

Only **metadata variables** — values loaded before the call starts (from the batch row, API trigger, or pre-call function). You cannot use variables captured during the call, because the AI has not started yet.

**Expression format** (same as Pathway node conditions, expression type only):

```
(metadata.language == 'english')
(metadata.opted_out == True)
((metadata.score > 5) AND (metadata.tier == 'gold'))
```

Rules:

* Every comparison must be wrapped in `( )`.
* String values use single quotes: `'english'`
* Boolean values: `True` or `False` (capital first letter)
* Combine with `AND` / `OR` (uppercase), wrapped in an extra `( )`:
  `((metadata.a == 'x') AND (metadata.b == True))`
* Operators: `==` `!=` `>` `<` `>=` `<=`

### Conditions vs key options

| Situation | Use |
| - | - |
| You already know the route from pre-call data | **Condition** |
| The caller needs to choose by pressing a key | **Key option** |
| Both apply | Conditions are checked first; key options run only if no condition matched |

***

## Post-call variables

When a call ends while still in the IVR phase (the AI never started), there is no conversation for the AI to analyse. You can configure each IVR node to save **static post-call values** instead, so your analytics and workflows still receive meaningful data.

### Toggle behaviour

| Setting | What happens |
| - | - |
| **Off** (default) | The AI runs post-call analysis on whatever transcript exists. For short IVR-only calls this may produce incomplete results. |
| **On** | The values you define here are saved directly. No AI post-call analysis runs. |

The values from whichever IVR node the call was on **when it ended** are the ones that get saved. If the caller hangs up at node A, node A's values are used. If the caller pressed 1 and reached node B before dropping, node B's values are used.

### Setting values

When the toggle is on, you see a table with three columns: **Variable name**, **Type**, and **Value**.

Two variables are pre-filled by default because they drive most analytics, workflows, and CRM updates:

| Variable | Type | What to set it to |
| - | - | - |
| `conversation_status` | Boolean | `true` if this node represents a converted / successful outcome, `false` otherwise |
| `disposition_reason` | Text | A short description of why the call ended here — e.g. *"No response to IVR menu"*, *"Opted out"*, *"Routed to sales"* |

You can add more variables to match any post-call variables defined on your agent.

**Variable types:**

| Type | Use for |
| - | - |
| Text | Words, sentences, labels |
| Boolean | True / false values |
| Number | Counts, scores, durations |
| Selector | A value from a fixed list |
| Object | Structured JSON data |

> [!TIP]
>
> Every IVR node that could be the last node on a call should have **Post-call variables** configured. At minimum, set `conversation_status` and `disposition_reason` so your analytics are always populated.

***

## Example: language selection menu

```
[IVR: lang_menu — starting node]
  Message: "Hello {{customer_name}}. Press 1 for English, press 2 for Hindi."
  Timeout: 8s  |  Max Retries: 2
  Key 1 → english_main (AI node)
  Key 2 → hindi_main   (AI node)
  No Input → lang_menu (retry)
  Invalid  → lang_menu (retry)
  Post-call variables (ON):
    conversation_status = false
    disposition_reason  = "No response to language menu"
```

After pressing 1, the call moves to `english_main` — an AI capability node — and the normal voice conversation begins.

***

## Common mistakes

| Mistake | What goes wrong | Fix |
| - | - | - |
| No starting IVR node set | Call starts on a random node | Mark exactly one node as the starting node |
| `next_capability` name does not exist | Call drops | Check that every key option points to a real node name |
| Max Retries set to 0 | Message plays once and immediately routes, no wait | Set Max Retries to 1 or higher |
| `Hang Up` node with key options | Key options are ignored | Remove options from hangup nodes |
| Post-call toggle off on a pure-IVR call | Analytics receive incomplete or empty values | Turn on post-call variables for any terminal IVR node |


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