IVR Statistics Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Metrics Reference
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are IVR Statistics?

IVR Statistics is an analytics module that tracks and reports on IVR (Interactive Voice Response) menu interactions. It provides insights into caller behavior, option popularity, timeout rates, and overall IVR effectiveness.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  IVR Statistics Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  IVR Handler (Lua)                                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        ivr_menu.lua                                      │   │
│  │                                                          │   │
│  │  Caller presses option                                   │   │
│  │  ├─ Log action to ivr_stats table                       │   │
│  │  ├─ Record digit pressed                                │   │
│  │  ├─ Track wait time                                     │   │
│  │  └─ Store destination                                   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Logged to Database                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        public.ivr_stats                                  │   │
│  │                                                          │   │
│  │  ivr_id | action | digit | wait_time | created_at       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Queried by Frontend                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        IVRStatsPage.tsx                                  │   │
│  │                                                          │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │ Total: 1,234 │ Options: 987 │ Timeout: 145 │Fail: 12│ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  │                                                          │   │
│  │  Charts: Digit breakdown, Action breakdown, Success rate │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.ivr_stats`	IVR interaction logs
`public.ivr_menus`	IVR menu definitions

Key Files

File	Description
`modules/ivrStats/IVRStatsPage.tsx`	Analytics page

---

2. Module Overview (Commercial/Business)

Business Value

IVR Statistics provides caller behavior insights:

Without IVR Stats	With IVR Stats
Unknown usage	Full analytics
Guess at performance	Data-driven optimization
Hidden problems	Visible timeouts/failures
No improvement path	Clear optimization targets

Use Cases

IVR Optimization

- Identify most-used options

- Simplify menu structure

Problem Detection

- High timeout rates

- Frequent failures

Capacity Planning

- Call volume trends

- Peak hour analysis

Customer Experience

- Wait time analysis

- Success rate tracking

Feature Highlights

Feature	Benefit
Total Interactions	Volume tracking
Option Presses	Popularity analysis
Timeouts	Navigation issues
Failures	System problems
Digit Breakdown	Option popularity
Success Rate	IVR effectiveness

---

3. Module Overview (End User/Administrator)

What Can You Do?

View IVR interaction statistics
Filter by date range
Filter by action type
See digit press distribution
Analyze success/timeout rates
Export detailed reports

IVR Statistics Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              IVR Statistics                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Filters:                                                       │
│  ├─ IVR Menu: [Main Menu ▼]                                    │
│  ├─ Start Date: [01/01/2026]                                   │
│  ├─ End Date: [01/16/2026]                                     │
│  └─ Action Type: [All ▼]                                       │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Total       │ Option      │ Timeouts    │ Failures        │ │
│  │ Interactions│ Presses     │             │                 │ │
│  │   1,234     │    987      │    145      │     12          │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────┐  ┌───────────────────────────────────┐ │
│  │ Timing Statistics   │  │ Most Pressed Digit                │ │
│  │                     │  │                                   │ │
│  │ Avg Wait: 8.5s      │  │ Digit 1: Sales (45%)             │ │
│  │ Avg Duration: 35s   │  │                                   │ │
│  └─────────────────────┘  └───────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────┐  ┌───────────────────────────────────┐ │
│  │ Digit Breakdown     │  │ Action Breakdown                  │ │
│  │                     │  │                                   │ │
│  │ 1: ████████ 45%     │  │ Option: ████████████ 80%          │ │
│  │ 2: █████ 25%        │  │ Timeout: ███ 12%                  │ │
│  │ 3: ███ 15%          │  │ Direct: █ 5%                      │ │
│  │ 0: ██ 10%           │  │ Failure: ░ 1%                     │ │
│  │ #: █ 5%             │  │ Invalid: ░ 2%                     │ │
│  └─────────────────────┘  └───────────────────────────────────┘ │
│                                                                 │
│  [Export Summary] [Export Details]                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Select IVR: Must select an IVR menu first to view statistics.

TIP

Date Range: Limit date range to avoid slow queries.

NOTE

Export: Export detailed data for external analysis.

---

4. Metrics Reference

Summary Cards

Metric	Description
Total Interactions	All IVR entries
Option Presses	Valid digit presses
Timeouts	No response within limit
Failures	System errors

Action Types

Action	Description
Option Pressed	Caller pressed valid digit
Timeout	No response from caller
Failure	System or config error
Invalid	Invalid digit pressed
Direct Dial	Extension dialed directly
Exit	Caller hung up

Timing Metrics

Metric	Description
Average Wait Time	Time before digit press
Average Duration	Total IVR time

Success Metrics

Metric	Calculation
Success Rate	Options / Total × 100%
Timeout Rate	Timeouts / Total × 100%
Failure Rate	Failures / Total × 100%

---

5. Common Scenarios & Examples

Scenario 1: Identify Popular Options

Select IVR menu
View Digit Breakdown chart
Note most-pressed digits
Consider reordering menu

Scenario 2: Reduce Timeouts

Check Timeout Rate
If high (>20%), menu may be confusing
Simplify options
Shorten prompts

Scenario 3: Monthly Report

Set date range for month
View all metrics
Export Summary
Share with management

Scenario 4: Troubleshoot Failures

Filter by "Failure" action type
View Call Details table
Identify patterns
Fix configuration issues

---

6. Limitations & Important Notes

Technical Notes

NOTE

Historical Data: Statistics depend on logging being enabled.

NOTE

Select IVR First: Must choose an IVR to view stats.

WARNING

Large Ranges: Long date ranges may be slow.

Best Practices

Regular Review: Check stats weekly/monthly
Watch Timeouts: High timeout = confusing menu
Watch Failures: Any failures need investigation
Export Data: Archive important stats
Optimize Menus: Use data to improve IVR

Target Benchmarks

Metric	Target
Success Rate	> 85%
Timeout Rate	< 10%
Failure Rate	< 1%
Avg Wait Time	< 15 seconds

---

7. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No data	Stats not logged	Check IVR logging
High timeouts	Long/confusing prompts	Simplify menu
High failures	Config errors	Check IVR settings
High invalid	Wrong key mapping	Review option numbers
No call details	Pagination	Use Next/Previous

Diagnostic SQL

IVR statistics summary:

Sql

SELECT 
  action,
  COUNT(*) as count,
  AVG(wait_time) as avg_wait
FROM public.ivr_stats
WHERE ivr_id = [ivr_id]
  AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY action;

Most pressed digits:

Sql

SELECT 
  digit,
  COUNT(*) as presses
FROM public.ivr_stats
WHERE ivr_id = [ivr_id]
  AND action = 'option_pressed'
GROUP BY digit
ORDER BY presses DESC;

---

8. Glossary

Term	Definition
IVR	Interactive Voice Response
Interaction	Single caller entering IVR
Option Press	Valid digit selection
Timeout	No caller response
Direct Dial	Extension dialed in IVR
Success Rate	Percentage completing IVR

---

Lua Script Status ℹ️

No Dedicated Handler Required

Component	Status
IVR Statistics	ℹ️ Reporting module - reads logs from `public.ivr_stats`

IVR Statistics is a frontend analytics module. IVR interactions are logged by the IVR handler (ivr_menu.lua) to public.ivr_stats. This module only reads and displays that data.

---

Documentation last updated: January 2026

IVR Statistics Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are IVR Statistics?

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?

IVR Statistics Interface

Quick Tips

4. Metrics Reference

Summary Cards

Action Types

Timing Metrics

Success Metrics

5. Common Scenarios & Examples

Scenario 1: Identify Popular Options

Scenario 2: Reduce Timeouts

Scenario 3: Monthly Report

Scenario 4: Troubleshoot Failures

6. Limitations & Important Notes

Technical Notes

Best Practices

Target Benchmarks

7. Troubleshooting Tips

Common Issues

Diagnostic SQL

8. Glossary

Lua Script Status ℹ️

No Dedicated Handler Required