IVR Menus

Interactive Voice Response (IVR) menus let you present options to callers and route them based on their selections. Create sophisticated, multi-level menus with branching logic.

IVR Basics

An IVR menu:

Plays a greeting/prompt to the caller
Collects DTMF (keypad) input
Routes based on the selection
Can branch to other menus or destinations

┌─────────────────────┐
│   Play Prompt       │
│ "Press 1 for Sales" │
└──────────┬──────────┘
           │
      Wait for Input
           │
    ┌──────┴──────┐
    │             │
    ▼             ▼
  Input=1      Input=2
    │             │
    ▼             ▼
Route to    Route to
  Sales      Support

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "prompt": "Welcome to our company. Press 1 for sales, 2 for support, or 3 for billing.",
    "language": "en-US",
    "options": [
      {
        "digit": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "digit": "2",
        "destination": "+14155552674",
        "destination_type": "phone_number"
      },
      {
        "digit": "3",
        "destination": "+14155552675",
        "destination_type": "phone_number"
      },
      {
        "digit": "0",
        "destination": "menu_operator",
        "destination_type": "ivr_menu"
      }
    ]
  }'

Response:

{
  "menu_id": "menu_abc123",
  "name": "Main Menu",
  "prompt": "Welcome to our company. Press 1 for sales, 2 for support, or 3 for billing.",
  "options": [
    {
      "digit": "1",
      "destination": "+14155552673",
      "destination_type": "phone_number"
    },
    // ... more options
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

Required Parameters

Parameter	Type	Description
`name`	string	Friendly name for this menu
`prompt`	string	Message to play to caller
`options`	array	Menu options and routing

Optional Parameters

Parameter	Type	Default	Description
`language`	string	`en-US`	Language for TTS
`voice`	string	`female`	Voice gender
`max_digits`	integer	1	Max digits to collect
`timeout`	integer	10	Seconds to wait for input
`max_attempts`	integer	3	Retries before fallback
`interrupt_on_dtmf`	boolean	`true`	Allow interrupt
`description`	string	-	Internal description

Using Pre-Recorded Prompts

Instead of text-to-speech, use audio files:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Menu",
    "audio_url": "https://example.com/sales-menu.mp3",
    "options": [
      {
        "digit": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "digit": "2",
        "destination": "menu_product_info",
        "destination_type": "ivr_menu"
      }
    ]
  }'

Nested Menus

Create multi-level menus by routing to other menus:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "prompt": "Press 1 for sales, 2 for support.",
    "options": [
      {
        "digit": "1",
        "destination": "menu_sales",
        "destination_type": "ivr_menu"
      },
      {
        "digit": "2",
        "destination": "menu_support",
        "destination_type": "ivr_menu"
      }
    ]
  }'

Then create the submenu:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Menu",
    "prompt": "Press 1 for new customers, 2 for existing customers, or 0 to go back.",
    "options": [
      {
        "digit": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "digit": "2",
        "destination": "+14155552674",
        "destination_type": "phone_number"
      },
      {
        "digit": "0",
        "destination": "menu_main",
        "destination_type": "ivr_menu"
      }
    ]
  }'

Each option specifies what happens when the digit is pressed:

Route to Phone Number

{
  "digit": "1",
  "destination": "+14155552673",
  "destination_type": "phone_number"
}

Route to Queue

{
  "digit": "1",
  "destination": "queue_support",
  "destination_type": "queue"
}

{
  "digit": "1",
  "destination": "menu_sales",
  "destination_type": "ivr_menu"
}

Send to Voicemail

{
  "digit": "1",
  "destination": "voicemail_sales",
  "destination_type": "voicemail"
}

{
  "digit": "*",
  "action": "repeat_menu"
}

{
  "digit": "0",
  "action": "previous_menu"
}

Handling Invalid Input

Define what happens if caller enters invalid input:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "prompt": "Press 1 for sales or 2 for support.",
    "options": [
      {
        "digit": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "digit": "2",
        "destination": "+14155552674",
        "destination_type": "phone_number"
      }
    ],
    "invalid_input": {
      "message": "Sorry, that selection is invalid. Please try again.",
      "max_attempts": 3,
      "fallback": {
        "destination": "+14155552675",
        "destination_type": "phone_number",
        "message": "Connecting you to an agent..."
      }
    }
  }'

Timeout Handling

Define behavior when no input is received:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "prompt": "Press 1 for sales or 2 for support.",
    "timeout": 15,
    "timeout_action": {
      "message": "No selection made. Connecting to an agent.",
      "destination": "+14155552675",
      "destination_type": "phone_number"
    },
    "options": [
      // ... options
    ]
  }'

Dynamic Prompts

Generate prompts on-the-fly based on call context:

# Create a call with dynamic IVR
curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "call_control": {
      "on_answered": [
        {
          "action": "play_audio",
          "message": "Hello John. You have 3 new messages. Press 1 to listen, 2 to delete, or 3 to skip.",
          "language": "en-US"
        },
        {
          "action": "gather_dtmf",
          "max_digits": 1,
          "timeout": 10,
          "routes": [
            {
              "digit": "1",
              "action": "transfer",
              "destination": "+14155552673"
            }
          ]
        }
      ]
    }
  }'

Multi-Digit Input

Collect multiple digits in an IVR:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Account Lookup",
    "prompt": "Please enter your 6-digit account number.",
    "max_digits": 6,
    "timeout": 20,
    "finish_key": "#",
    "options": [
      {
        "pattern": "[0-9]{6}",
        "destination": "webhook_lookup",
        "destination_type": "webhook"
      }
    ]
  }'

Recording IVR Selections

Access caller selections through webhooks:

{
  "event": "ivr.input_received",
  "data": {
    "call_id": "call_xyz789",
    "menu_id": "menu_abc123",
    "input": "2",
    "input_type": "dtmf",
    "received_at": "2024-01-15T10:31:00Z"
  }
}

Advanced Routing with Webhooks

Route IVR selections to your API for custom logic:

curl -X POST https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Menu",
    "prompt": "Enter your selection.",
    "options": [
      {
        "pattern": "[0-9]+",
        "destination": "https://your-api.example.com/process-selection",
        "destination_type": "webhook"
      }
    ]
  }'

Your webhook receives:

{
  "call_id": "call_xyz789",
  "menu_id": "menu_abc123",
  "input": "5",
  "from": "+14155552672",
  "to": "+14155552671"
}

Respond with routing:

{
  "destination": "+14155552673",
  "destination_type": "phone_number",
  "message": "Routing you to sales..."
}

Managing IVR Menus

List All Menus

curl https://api.audian.com:8443/v2/ivr-menus \
  -H "X-Auth-Token: YOUR_API_KEY"

curl https://api.audian.com:8443/v2/ivr-menus/menu_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

curl -X PATCH https://api.audian.com:8443/v2/ivr-menus/menu_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Updated prompt message"
  }'

curl -X DELETE https://api.audian.com:8443/v2/ivr-menus/menu_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Testing IVR Menus

Test menu routing without actual calls:

curl -X POST https://api.audian.com:8443/v2/ivr-menus/menu_abc123/test \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "2"
  }'

Response shows which route matches:

{
  "input": "2",
  "matched_option": {
    "digit": "2",
    "destination": "+14155552674",
    "destination_type": "phone_number"
  }
}

IVR Analytics

Get usage statistics for your menus:

curl "https://api.audian.com:8443/v2/ivr-menus/menu_abc123/analytics?period=week" \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "menu_id": "menu_abc123",
  "period": "week",
  "total_calls": 1250,
  "selections": [
    {
      "digit": "1",
      "count": 750,
      "percentage": 60
    },
    {
      "digit": "2",
      "count": 400,
      "percentage": 32
    },
    {
      "timeout": 100,
      "percentage": 8
    }
  ]
}

Code Examples

const axios = require('axios');

async function createDynamicMenu(customerName) {
  const response = await axios.post(
    'https://api.audian.com:8443/v2/ivr-menus',
    {
      name: `Menu for ${customerName}`,
      prompt: `Welcome ${customerName}! Press 1 for billing or 2 for support.`,
      options: [
        {
          digit: '1',
          destination: '+14155552673',
          destination_type: 'phone_number'
        },
        {
          digit: '2',
          destination: '+14155552674',
          destination_type: 'phone_number'
        }
      ]
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
      }
    }
  );

  return response.data.menu_id;
}

Python - Nested Menus

import requests
import os

def create_menu_hierarchy():
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}",
        'Content-Type': 'application/json'
    }

    # Create main menu
    main_response = requests.post(
        'https://api.audian.com:8443/v2/ivr-menus',
        json={
            'name': 'Main Menu',
            'prompt': 'Press 1 for sales or 2 for support.',
            'options': [
                {
                    'digit': '1',
                    'destination': 'menu_sales',
                    'destination_type': 'ivr_menu'
                },
                {
                    'digit': '2',
                    'destination': 'menu_support',
                    'destination_type': 'ivr_menu'
                }
            ]
        },
        headers=headers
    )

    print(f"Created menu: {main_response.json()['menu_id']}")

    # Create sales submenu
    sales_response = requests.post(
        'https://api.audian.com:8443/v2/ivr-menus',
        json={
            'name': 'Sales Menu',
            'prompt': 'Press 1 for new products or 2 for pricing.',
            'options': [
                {
                    'digit': '1',
                    'destination': '+14155552673',
                    'destination_type': 'phone_number'
                },
                {
                    'digit': '2',
                    'destination': '+14155552674',
                    'destination_type': 'phone_number'
                }
            ]
        },
        headers=headers
    )

    print(f"Created submenu: {sales_response.json()['menu_id']}")

Best Practices

Keep menus simple: Offer 3-4 options per menu
Clear prompts: Use natural language
Provide escape: Always offer option to speak to agent
Test thoroughly: Test all menu paths
Monitor usage: Check analytics for optimization
Support repetition: Allow callers to repeat menu
Timeout handling: Route to agent on timeout
Fallback options: Define behavior for invalid input

IVR Menus

IVR Basics

Creating an IVR Menu

IVR Menu Parameters

Required Parameters

Optional Parameters

Using Pre-Recorded Prompts

Nested Menus

Menu Options

Route to Phone Number

Route to Queue

Route to Another Menu

Send to Voicemail

Repeat Current Menu

Return to Previous Menu

Handling Invalid Input

Timeout Handling

Dynamic Prompts

Multi-Digit Input

Recording IVR Selections

Advanced Routing with Webhooks

Managing IVR Menus

List All Menus

Get Menu Details

Update Menu

Delete Menu

Testing IVR Menus

IVR Analytics

Code Examples

Node.js - Dynamic Menu

Python - Nested Menus

Best Practices

Next Steps

IVR Basics​

Creating an IVR Menu​

IVR Menu Parameters​

Required Parameters​

Optional Parameters​

Using Pre-Recorded Prompts​

Nested Menus​

Menu Options​

Route to Phone Number​

Route to Queue​

Route to Another Menu​

Send to Voicemail​

Repeat Current Menu​

Return to Previous Menu​

Handling Invalid Input​

Timeout Handling​

Dynamic Prompts​

Multi-Digit Input​

Recording IVR Selections​

Advanced Routing with Webhooks​

Managing IVR Menus​

List All Menus​

Get Menu Details​

Update Menu​

Delete Menu​

Testing IVR Menus​

IVR Analytics​

Code Examples​

Node.js - Dynamic Menu​

Python - Nested Menus​

Best Practices​

Next Steps​

IVR Basics

Creating an IVR Menu

IVR Menu Parameters

Required Parameters

Optional Parameters

Using Pre-Recorded Prompts

Nested Menus

Menu Options

Route to Phone Number

Route to Queue

Route to Another Menu

Send to Voicemail

Repeat Current Menu

Return to Previous Menu

Handling Invalid Input

Timeout Handling

Dynamic Prompts

Multi-Digit Input

Recording IVR Selections

Advanced Routing with Webhooks

Managing IVR Menus

List All Menus

Get Menu Details

Update Menu

Delete Menu

Testing IVR Menus

IVR Analytics

Code Examples

Node.js - Dynamic Menu

Python - Nested Menus

Best Practices

Next Steps