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. Use IVR to:
  • Route calls to different agents based on department (Sales, Support, etc.)
  • Collect information before the conversation (account number, language preference)
  • Provide multi-language support with language selection menus
IVR is currently supported for Plivo phone numbers only.

​
How IVR Works

  1. Caller dials your phone number
  2. Welcome message plays (optional)
  3. IVR menu prompts caller to press a digit
  4. Based on input, either:
    • Move to next menu/collection step
    • Connect to the appropriate Voice AI agent
  5. Agent receives all collected data 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

​
Top-Level Config

FieldTypeDefaultDescription
enabledbooleanfalseEnable or disable IVR
voicestringPolly.JoannaText-to-speech voice
welcome_messagestring-Played once when call connects
timeoutinteger5Seconds to wait for input
max_retriesinteger2Retries on invalid input
invalid_input_messagestringInvalid input. Please try again.Error message
no_input_messagestringNo input received. Goodbye.Timeout message
stepsarrayrequiredIVR flow steps
default_agent_idstring-Fallback agent if no option-level agent

​
Available Voices

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

​
Step Types

Presents options for the caller to select using keypad. 
{
  "step_id": "department",
  "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"}
  ]
}
Menu Option Fields:
FieldTypeRequiredDescription
digitstringYesKey to press ("1", "2", etc.)
labelstringYesStored in collected data
agent_idstringNoRoute to specific agent
context_labelstringNoAdditional context for agent

​
Collect Step

Collects multi-digit input like account numbers or PINs. 
{
  "step_id": "account",
  "type": "collect",
  "prompt": "Enter your 6-digit account number.",
  "field_name": "account_number",
  "num_digits": 6,
  "next_step": "pin_step"
}
Collect Fields:
FieldTypeDescription
num_digitsintegerExact digits required
min_digitsintegerMinimum digits (if num_digits not set)
max_digitsintegerMaximum digits (if num_digits not set)
finish_on_keystringSubmit key (default: #)
Control the flow between steps:
FieldUsageDescription
next_stepLinear flowGo to specified step after this one
conditional_nextBranchingDifferent step based on digit: {"1": "step_a", "2": "step_b"}
(neither)End flowRoutes to agent

​
Data Passed to Agent

All collected data is available in recipient_data: 
{
  "department": "Sales",
  "department_context": "sales_inquiry",
  "account_number": "123456",
  "ivr_completed_at": "2026-01-15T10:30:00Z"
}
Use these in your agent prompt: "Customer selected {department}. Account: {account_number}"

​
Examples

​
Simple Department Routing

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"}
        ]
      }
    ]
  }
}

​
Multi-Language with Branching

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"}
        ]
      }
    ]
  }
}

​
Account Verification Flow

Collect account details before connecting: 
{
  "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 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