Skip to main content

​
What is IVR?

IVR (Interactive Voice Response) lets callers navigate menus using their phone keypad before connecting to a Voice AI agent.

Route by Department

Send callers to Sales, Support, or Billing agents automatically

Collect Information

Gather account numbers, PINs, or preferences before the conversation

Multi-Language Support

Let callers choose their preferred language before connecting
IVR is currently supported for Plivo phone numbers only.

​
How IVR Works

All collected data (department choice, account number, etc.) is passed to the agent as context.

​
Setting Up IVR via API

Add ivr_config to the Set Inbound Agent API: 
curl -X POST "https://api.bolna.ai/inbound/setup" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-default-agent-id",
    "phone_number_id": "your-phone-number-id",
    "ivr_config": {
      "enabled": true,
      "voice": "Polly.Aditi",
      "welcome_message": "Welcome to Acme Corp.",
      "steps": [
        {
          "step_id": "main_menu",
          "type": "menu",
          "prompt": "Press 1 for Sales. Press 2 for Support.",
          "field_name": "department",
          "options": [
            {"digit": "1", "label": "Sales", "agent_id": "sales-agent-id"},
            {"digit": "2", "label": "Support", "agent_id": "support-agent-id"}
          ]
        }
      ]
    }
  }'

​
IVR Configuration Reference

​
Top-Level Config

FieldTypeDefaultDescription
enabledbooleanfalseEnable or disable IVR
voicestringPolly.JoannaText-to-speech voice for IVR prompts
welcome_messagestring-Played once when the call connects
timeoutinteger5Seconds to wait for caller input
max_retriesinteger2Retry count on invalid input
invalid_input_messagestringInvalid input. Please try again.Played on wrong key press
no_input_messagestringNo input received. Goodbye.Played on timeout
stepsarrayrequiredIVR flow steps (see below)
default_agent_idstring-Fallback agent when no option-level agent is set

​
Available Voices

VoiceLanguage
Polly.AditiHindi + Indian English
Polly.RaveenaIndian English
Polly.JoannaUS English (Female)
Polly.MatthewUS English (Male)
Polly.AmyBritish English (Female)

​
Step Types

​
Step Navigation

Control flow between steps:
FieldUsageDescription
next_stepLinear flowGo to specified step after this one
conditional_nextBranchingRoute based on digit: {"1": "step_a", "2": "step_b"}
(neither)End flowRoutes to the assigned agent
Use conditional_next for language selection or department-specific sub-menus. Combine with next_step for sequential data collection.

​
Data Passed to Agent

All collected IVR data is available in recipient_data: 
{
  "department": "Sales",
  "department_context": "sales_inquiry",
  "account_number": "123456",
  "ivr_completed_at": "2026-01-15T10:30:00Z"
}
Reference these in your agent prompt: 
Customer selected {department}. Account: {account_number}
Learn more about using dynamic variables in Using Context.

​
Examples

Route calls to different agents based on selection:
{
  "ivr_config": {
    "enabled": true,
    "voice": "Polly.Aditi",
    "welcome_message": "Welcome to Acme Corp.",
    "steps": [
      {
        "step_id": "department",
        "type": "menu",
        "prompt": "Press 1 for Sales. Press 2 for Support. Press 3 for Billing.",
        "field_name": "department",
        "options": [
          {"digit": "1", "label": "Sales", "agent_id": "sales-agent-uuid"},
          {"digit": "2", "label": "Support", "agent_id": "support-agent-uuid"},
          {"digit": "3", "label": "Billing", "agent_id": "billing-agent-uuid"}
        ]
      }
    ]
  }
}
Language selection followed by department menu:
{
  "ivr_config": {
    "enabled": true,
    "voice": "Polly.Aditi",
    "welcome_message": "Welcome. Swagat hai.",
    "steps": [
      {
        "step_id": "language",
        "type": "menu",
        "prompt": "For English press 1. Hindi ke liye 2 dabayein.",
        "field_name": "language",
        "options": [
          {"digit": "1", "label": "English"},
          {"digit": "2", "label": "Hindi"}
        ],
        "conditional_next": {"1": "menu_en", "2": "menu_hi"}
      },
      {
        "step_id": "menu_en",
        "type": "menu",
        "prompt": "Press 1 for Sales. Press 2 for Support.",
        "field_name": "department",
        "options": [
          {"digit": "1", "label": "Sales", "agent_id": "english-sales-agent"},
          {"digit": "2", "label": "Support", "agent_id": "english-support-agent"}
        ]
      },
      {
        "step_id": "menu_hi",
        "type": "menu",
        "prompt": "Sales ke liye 1 dabayein. Support ke liye 2 dabayein.",
        "field_name": "department",
        "options": [
          {"digit": "1", "label": "Sales", "agent_id": "hindi-sales-agent"},
          {"digit": "2", "label": "Support", "agent_id": "hindi-support-agent"}
        ]
      }
    ]
  }
}
Collect account details before connecting to an agent:
{
  "ivr_config": {
    "enabled": true,
    "voice": "Polly.Aditi",
    "welcome_message": "Welcome to your bank.",
    "default_agent_id": "bank-agent-uuid",
    "steps": [
      {
        "step_id": "account",
        "type": "collect",
        "prompt": "Please enter your 10-digit account number.",
        "field_name": "account_number",
        "num_digits": 10,
        "next_step": "pin"
      },
      {
        "step_id": "pin",
        "type": "collect",
        "prompt": "Enter your 4-digit PIN.",
        "field_name": "pin",
        "num_digits": 4
      }
    ]
  }
}

​
Disable IVR

To disable IVR and route calls directly to your agent: 
curl -X POST "https://api.bolna.ai/inbound/setup" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "phone_number_id": "your-phone-number-id",
    "ivr_config": {"enabled": false}
  }'

​
Next Steps

Inbound Call Setup

Basic inbound calling configuration

Connect Plivo

Use your own Plivo phone numbers

Using Context

Pass dynamic data to your agents