---
title: "IVR Statistics Module Documentation"
description: "Documentation for IVR Stats"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Metrics Reference](#4-metrics-reference)
7. [Common Scenarios & Examples](#5-common-scenarios--examples)
8. [Limitations & Important Notes](#6-limitations--important-notes)
9. [Troubleshooting Tips](#7-troubleshooting-tips)
10. [Glossary](#8-glossary)
11. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
---

## Navigation & Access

To access the IVR Statistics & Analytics dashboard:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Reports**.
3. Under **IVR Reports**, click **IVR Stats** (`/reports/ivr/stats`).
4. Select the target IVR auto attendant from the dropdown and configure date filters to review interaction metrics, digit heatmaps, and timeout ratios.

---

## Screenshots & Visual Interface

### IVR Statistics & Interaction Analytics Console
Interactive performance dashboard featuring aggregate interaction KPIs, option selection frequency graphs, menu dwell times, digit breakdown charts, and detailed caller interaction records.
![IVR Statistics Report](/screenshots/reports/ivr/ivr-stats-list.png)

---

## 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

```
┌─────────────────────────────────────────────────────────────────┐
│                  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 │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **IVR Optimization**
   - Identify most-used options
   - Simplify menu structure

2. **Problem Detection**
   - High timeout rates
   - Frequent failures

3. **Capacity Planning**
   - Call volume trends
   - Peak hour analysis

4. **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

```
┌─────────────────────────────────────────────────────────────────┐
│              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

1. Select IVR menu
2. View Digit Breakdown chart
3. Note most-pressed digits
4. Consider reordering menu

### Scenario 2: Reduce Timeouts

1. Check Timeout Rate
2. If high (>20%), menu may be confusing
3. Simplify options
4. Shorten prompts

### Scenario 3: Monthly Report

1. Set date range for month
2. View all metrics
3. Export Summary
4. Share with management

### Scenario 4: Troubleshoot Failures

1. Filter by "Failure" action type
2. View Call Details table
3. Identify patterns
4. 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

1. **Regular Review**: Check stats weekly/monthly
2. **Watch Timeouts**: High timeout = confusing menu
3. **Watch Failures**: Any failures need investigation
4. **Export Data**: Archive important stats
5. **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 |

---

## 9. Model Context Protocol (MCP) AI Integration

The Ring2All Platform Copilot integrates with IVR analytics through the Model Context Protocol (MCP). Call flow architects, customer experience managers, and contact center leads can audit menu performance, analyze caller drop-offs, and discover popular menu branches via natural language dialogues.

### Exposed MCP Tools

| Tool Name | Operation | Primary Parameters | Description |
|:---|:---|:---|:---|
| `get_ivr_statistics` | Menu Performance Metrics | `ivrId` (number, optional), `name` (string, optional), `days` (number, optional, default: 30) | Retrieves caller interaction statistics for an IVR menu: total call volume, digit selection breakdown, timeout counts, direct dial requests, and average wait time. |
| `list_ivrs` | IVR Inventory | `search` (string, optional) | Lists all configured IVR menus to discover menu IDs, names, extensions, and operational contexts. |
| `get_ivr_status` | IVR Configuration Review | `name` (string) | Fetches the full DTMF key destination mapping (Press 1 for Sales, Press 2 for Support, etc.) to correlate against caller choices. |

### Operational Safeguards & Analytics Isolation

- **Domain Isolation**: Statistics queries filter strictly on `domain_id`. Interaction data from other business units or tenants remains invisible.
- **Read-Only Analytics**: Statistical queries run aggregate calculations (`COUNT`, `AVG`, `GROUP BY`) against `ss_logs.ivr_stats` without modifying telephony dialplans or audio files.
- **Zero-Latency Performance**: Aggregated reporting indices (`idx_ivr_stats_ivr_action_date`) ensure real-time analytics queries do not affect ongoing Telephony Server Lua call processing.

### Example MCP Payloads

#### 1. Querying 30-Day IVR Statistics (`get_ivr_statistics`)
```json
{
  "name": "Main Company IVR",
  "days": 30
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "ivrId": 4,
    "ivrName": "Main Company IVR",
    "extension": "5000",
    "periodDays": 30,
    "totalInteractions": 842,
    "actionsSummary": {
      "option_pressed": 690,
      "timeout": 88,
      "direct_dial": 42,
      "invalid": 22
    },
    "popularOptions": [
      { "digit": "1", "destination": "Ring Group: Sales", "count": 420 },
      { "digit": "2", "destination": "Call Queue: Support", "count": 210 },
      { "digit": "0", "destination": "Extension: 1001", "count": 60 }
    ]
  }
}
```

#### 2. Listing Configured IVRs (`list_ivrs`)
```json
{}
```

### Copilot Natural Language Prompts

- *"What is the most frequently pressed option on our Main Company IVR?"*
- *"How many callers timed out without pressing any digit on the IVR this month?"*
- *"Give me a breakdown of all IVR interactions over the last 7 days."*
- *"What percentage of callers use direct extension dialing when entering our auto attendant?"*

---

*Documentation last updated: January 2026*