IVR (Interactive Voice Response) Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
IVR Options
Destination Types
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Is an IVR?

An IVR (Interactive Voice Response) is an automated phone menu that plays audio prompts and routes callers based on DTMF key presses. Callers hear options like "Press 1 for Sales, Press 2 for Support" and are routed accordingly.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                     IVR System                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Caller enters IVR (via inbound route or transfer)              │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                     ivr.lua                              │   │
│  │                                                          │   │
│  │  1. Answer call                                          │   │
│  │  2. Play welcome message (ivr-welcome.wav)               │   │
│  │  3. Play instructions (ivr-instructions.wav)             │   │
│  │  4. Wait for DTMF (digit 0-9, *, #)                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  User presses "1"                                        │   │
│  │                                                          │   │
│  │  1. Query public.ivrs_options WHERE digit = '1'         │   │
│  │  2. Match found! action=transfer, destination=Sales      │   │
│  │  3. Log statistics (if enabled)                          │   │
│  │  4. Transfer to Sales Queue                              │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  No match or timeout?                                    │   │
│  │                                                          │   │
│  │  1. Play invalid message                                 │   │
│  │  2. Increment retry counter                              │   │
│  │  3. If < max_failures: repeat menu                       │   │
│  │  4. If >= max_failures: play exit message, hangup        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.ivrs`	IVR menu definitions
`public.ivrs_options`	DTMF options per IVR
`public.ivr_stats`	Statistics tracking
`public.dialplan_registry`	Destination lookup

Key Files

File	Description
`admin/apps/web/src/modules/ivrs/`	Frontend module
`admin/apps/web/src/i18n/en/ivrs.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/ivr/ivr.lua`	Main IVR handler
`telephony/freeswitch/lua/main/xml_handlers/routing/ivr.lua`	IVR routing handler
`telephony/freeswitch/lua/main/services/ivr_stats_logger.lua`	Statistics logger

---

2. Module Overview (Commercial/Business)

Business Value

IVRs provide automated call routing:

Without IVR	With IVR
Receptionist answers every call	Automated menu routing
Manual transfers	Self-service navigation
Limited hours	24/7 availability
Inconsistent experience	Professional greeting

Use Cases

Main Auto-Attendant

- Welcome callers

- Route to departments

After-Hours Greeting

- Inform of business hours

- Offer voicemail

Multi-Level Menus

- Sales → Products/Services

- Support → Billing/Technical

Language Selection

- English, Spanish, etc.

- Route to language-specific queues

Feature Highlights

Feature	Benefit
Custom Prompts	Branded audio messages
Multiple Options	0-9, , # for routing
Nested IVRs	Multi-level menus
Direct Dial	Dial extensions from IVR
Timeout Handling	Default destination
Failure Handling	Max retries limit
Statistics	Track usage patterns

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create IVR menus with audio prompts
Configure multiple DTMF options
Set timeout and retry limits
Route to extensions, queues, other IVRs
Enable direct extension dialing
Track IVR statistics

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating an IVR Menu                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: General                                                   │
│  ├─ Name: "Main Menu"                                          │
│  ├─ Welcome Message: main-welcome.wav                          │
│  ├─ Instructions: main-menu.wav                                │
│  ├─ Invalid Message: invalid-selection.wav                     │
│  ├─ Exit Message: goodbye.wav                                  │
│  ├─ Timeout: 5 seconds                                         │
│  ├─ Max Failures: 3                                            │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab: Options                                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Digits │ Destination        │ Enabled │                  │  │
│  ├────────┼────────────────────┼─────────┤                  │  │
│  │ 1      │ Sales Queue        │ ✓       │                  │  │
│  │ 2      │ Support Queue      │ ✓       │                  │  │
│  │ 3      │ Billing Extension  │ ✓       │                  │  │
│  │ 0      │ Operator (1000)    │ ✓       │                  │  │
│  │ *      │ Repeat Menu        │ ✓       │                  │  │
│  └───────────────────────────────────────────────────────────┘  │
│  [+ Add Option]                                                 │
│                                                                 │
│  Tab: Settings                                                  │
│  ├─ Allow Direct Dial: ✓                                       │
│  ├─ Timeout Destination: Voicemail                             │
│  ├─ Failure Destination: Operator                              │
│  └─ Track Statistics: ✓                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Keep Menus Short: 3-5 options is ideal for caller retention.

TIP

Option 0 = Operator: Standard convention for reaching a human.

CAUTION

Audio File Quality: Use clear, professional recordings.

---

4. Configuration Fields Reference

General Settings

Field	Description	Default
Name	IVR identifier	Required
Welcome Message	First audio played	ivr-welcome.wav
Instructions	Menu options audio	ivr-instructions.wav
Invalid Message	For wrong input	ivr-invalid.wav
Exit Message	When exiting IVR	ivr-goodbye.wav
Timeout (seconds)	Wait for input	5
Max Failures	Invalid attempts	3
Max Timeouts	Timeout attempts	3
Enabled	IVR active	On

Advanced Settings

Field	Description	Default
Inter-Digit Timeout	Between digits (ms)	2000
Min Digits	Minimum input	1
Max Digits	Maximum input	1
Allow Direct Dial	Dial extensions	Off
Track Statistics	Log usage	Off
Record Session	Record interaction	Off
Max Call Duration	Session limit	None
Event Webhook	API notification	None

Destination Settings

Field	Description
Timeout Destination	Route when no input
Failure Destination	Route after max failures
Background Music	Loop during wait

---

5. IVR Options

Option Configuration

Each IVR can have multiple options:

Field	Description	Example
Digits	DTMF trigger	1, 2, , #
Destination	Where to route	Sales Queue
Enabled	Option active	On/Off
Priority	Evaluation order	1, 2, 3

Common Digit Mappings

Digit	Typical Use
1	Sales / First option
2	Support / Second option
3	Billing / Third option
0	Operator / Live person
	Repeat menu
#	Exit / Main menu
9	Directory / Dial by name

Example Option Set

Plaintext

IVR: "Main Menu"
├─ 1 → Sales Queue
├─ 2 → Support Queue  
├─ 3 → Billing IVR (sub-menu)
├─ 0 → Operator Extension 1000
├─ * → Repeat (this IVR)
└─ # → Exit

---

6. Destination Types

Available Destinations

Type	Description	Example
Extension	Route to extension	1001
Queue	Route to call center queue	Sales Queue
IVR	Route to another IVR	Billing Menu
Ring Group	Route to ring group	Support Team
Conference	Route to conference	Meeting Room
Voicemail	Route to voicemail	General Mailbox
Direct Route	External number	+15055551234
Announcement	Play audio, hangup	After-hours
Feature Code	Execute feature	70 (echo test)

Transfer Actions

When an option is selected, the IVR can:

Transfer - Route to destination
IVR - Enter nested IVR menu
Repeat - Replay current menu

---

7. Common Scenarios & Examples

Scenario 1: Simple Auto-Attendant

IVR: "Main Menu"

Setting	Value
Welcome	"Thank you for calling ABC Company"
Instructions	"For Sales press 1, Support press 2, Operator press 0"
Timeout	5 seconds
Max Failures	3

Options:

Digit	Destination
1	Sales Queue
2	Support Queue
0	Extension 1000

IVR: "Main Menu"

Digit	Destination
1	Sales IVR
2	Support IVR

IVR: "Sales IVR"

Digit	Destination
1	New Customers Queue
2	Existing Customers Queue
	Main Menu (parent)

Scenario 3: After-Hours IVR

IVR: "After Hours"

Setting	Value
Welcome	"Thank you for calling. Our office is closed."
Instructions	"Leave a message after the tone, press 0 for emergency"
Timeout Destination	General Voicemail

Options:

Digit	Destination
0	On-Call Extension

---

8. Limitations & Important Notes

Technical Notes

NOTE

DTMF Interruption: Callers can press a digit during prompt playback.

WARNING

Audio File Paths: Ensure audio files exist in the language directory.

WARNING

Context Registration: IVR context must be in dialplan_registry.

Best Practices

Professional Audio: Use quality recordings
Short Menus: 3-5 options maximum
Consistent Layout: Option 0 = Operator
Timeout Handling: Always set default destination
Test Thoroughly: Verify all paths work
Track Statistics: Enable for optimization

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No audio	Wrong path	Check audio file exists
DTMF ignored	Timing issue	Increase timeout
Wrong destination	Option misconfigured	Check option mapping
Loops	Circular IVR reference	Review IVR destinations
No answer	IVR not enabled	Enable IVR

Diagnostic SQL

List IVRs:

Sql

SELECT id, name, context, timeout, max_failures, enabled
FROM public.ivrs
WHERE domain_id = [domain_id];

Check IVR options:

Sql

SELECT o.digits, o.action, o.destination, o.enabled
FROM public.ivrs_options o
JOIN public.ivrs i ON o.ivr_id = i.id
WHERE i.domain_id = [domain_id] AND i.name = 'Main Menu'
ORDER BY o.priority;

Check IVR statistics:

Sql

SELECT event_type, digit_pressed, destination, COUNT(*)
FROM public.ivr_stats
WHERE ivr_id = [ivr_id]
GROUP BY event_type, digit_pressed, destination
ORDER BY COUNT(*) DESC;

FreeSWITCH Logs

Bash

# Check IVR execution
grep "IVR" /var/log/freeswitch/freeswitch.log
grep "ivr.lua" /var/log/freeswitch/freeswitch.log

---

10. Glossary

Term	Definition
IVR	Interactive Voice Response - automated phone menu
DTMF	Dual-Tone Multi-Frequency - key press tones
Context	IVR identifier for routing
Option	DTMF digit + destination mapping
Nested IVR	IVR within IVR (sub-menu)
Timeout	No input wait time
Max Failures	Invalid input limit

---

Lua Script Status ✅

All Scripts Already Correct

Script	Status
`ivr/ivr.lua`	✅ Uses `public.domains`, `public.ivrs`, `public.ivrs_options`, `public.dialplan_registry`, `public.direct_dial`
`routing/ivr.lua`	✅ Routing handler
`ivr_stats_logger.lua`	✅ Statistics logger

No Lua fixes needed!

---

Documentation last updated: January 2026*

IVR (Interactive Voice Response) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is an IVR?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

General Settings

Advanced Settings

Destination Settings

5. IVR Options

Option Configuration

Common Digit Mappings

Example Option Set

6. Destination Types

Available Destinations

Transfer Actions

7. Common Scenarios & Examples

Scenario 1: Simple Auto-Attendant

Scenario 2: Multi-Level Menu

Scenario 3: After-Hours IVR

8. Limitations & Important Notes

Technical Notes

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

10. Glossary

Lua Script Status ✅

All Scripts Already Correct