> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetzy.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting System

> Generate advanced reports with agent metrics, temporal analysis, and export capabilities

The Reporting System provides comprehensive analytics for your conversational AI agents with advanced filtering, metrics tracking, and data export capabilities.

## Overview

The reporting system offers detailed insights into agent performance, call metrics, and conversion analytics with temporal analysis to help you optimize your AI agents.

<Info>
  All reports are generated in real-time and can be exported to CSV format for further analysis.
</Info>

## Getting Started

<Steps>
  <Step title="Access Reports">
    Navigate to the Reports section in your dashboard to begin generating analytics reports.
  </Step>

  <Step title="Select Agents">
    Choose which agents you want to include in your report from the available list.
  </Step>

  <Step title="Configure Filters">
    Set date ranges, status filters, and other criteria to focus your analysis.
  </Step>

  <Step title="Generate Report">
    Click "Generate Report" to create your comprehensive analytics report.
  </Step>
</Steps>

## Report Filters

### Basic Filters

Configure your report scope with these fundamental filters:

* **Agent Selection**: Choose specific agents or select all agents
* **Date Range**: Set start and end dates for your analysis period
* **Status Filter**: Filter by call status (completed, missed, failed, etc.)
* **Call Type**: Filter by inbound, outbound, or transferred calls

### Advanced Filters

Refine your analysis with additional criteria:

```typescript theme={null}
interface ReportFilters {
  agent_ids: string[];
  start_date: string;
  end_date: string;
  filters?: {
    status?: string[];
    call_type?: string[];
    min_duration?: number;
    max_duration?: number;
    min_nps_score?: number;
    max_nps_score?: number;
  };
}
```

**Duration Filters**:

* Set minimum and maximum call duration thresholds
* Analyze calls within specific time ranges

**NPS Score Filters**:

* Filter by Net Promoter Score ranges
* Focus on high or low satisfaction calls

## Agent Metrics

Each report provides comprehensive metrics for selected agents:

### Core Metrics

<Tabs>
  <Tab title="Call Statistics">
    * **Total Calls**: All initiated calls
    * **Completed Calls**: Successfully finished conversations
    * **Converted Calls**: Calls that achieved objectives
    * **Received Calls**: Inbound calls handled
    * **Outbound Calls**: Agent-initiated calls
    * **Transferred Calls**: Calls passed to human agents
  </Tab>

  <Tab title="Performance Metrics">
    * **Completion Rate**: Percentage of calls completed successfully
    * **Conversion Rate**: Percentage of calls that converted
    * **Contact Rate**: Percentage of leads successfully contacted
    * **Transfer Rate**: Percentage of calls transferred to humans
  </Tab>

  <Tab title="Duration Analysis">
    * **Average Duration**: Mean call length
    * **Total Conversation Time**: Sum of all call durations
    * **Duration Standard Deviation**: Variability in call lengths
    * **Billable Minutes**: Total charged conversation time
  </Tab>
</Tabs>

### Customer Satisfaction

<Info>
  NPS (Net Promoter Score) tracking is available for agents with NPS activation enabled.
</Info>

* **Average NPS Score**: Mean customer satisfaction rating
* **NPS Surveys Count**: Number of completed satisfaction surveys
* **NPS Response Rate**: Percentage of customers who responded to surveys

### Lead Management

Track your lead conversion funnel:

* **Unique Leads**: Total number of distinct leads
* **Contacted Leads**: Leads successfully reached
* **Converted Leads**: Leads that completed desired actions
* **Conversion from Contacted Rate**: Efficiency of contacted lead conversion

## Temporal Analysis

### Daily Breakdown

View performance trends over time with daily metrics:

```typescript theme={null}
daily_data: Array<{
  date: string;
  calls: number;
  unique_leads: number;
  contacted_leads: number;
  converted_leads: number;
  completed_calls: number;
  conversions: number;
  avg_duration: number;
  conversion_rate: number;
  // Additional metrics...
}>
```

**Key Daily Metrics**:

* Call volume trends
* Conversion rate fluctuations
* Duration patterns
* Lead engagement levels

### Hourly Analysis

Optimize scheduling with hourly performance data:

* **Peak Hours**: Identify most effective calling times
* **Conversion by Hour**: Success rates throughout the day
* **Duration Patterns**: Average call lengths by time of day

<Warning>
  Hourly analysis requires sufficient data volume for meaningful insights. Reports with fewer than 50 calls may show limited hourly patterns.
</Warning>

## Data Export

### CSV Export

Export your reports for external analysis:

<Steps>
  <Step title="Generate Report">
    Create your report with desired filters and date range.
  </Step>

  <Step title="Export Options">
    Choose CSV format and optionally specify a custom filename.
  </Step>

  <Step title="Download">
    The system will generate and download your CSV file with all report data.
  </Step>
</Steps>

**CSV Export Includes**:

* Agent metrics summary
* Daily temporal data
* Hourly analysis
* Status distribution
* Call details (if included in filters)

### Export Format

```typescript theme={null}
// Export request structure
{
  report_data: ReportData,
  format: 'csv',
  filename?: string // Optional custom filename
}
```

## Report Templates

### Predefined Templates

Use pre-configured templates for common reporting needs:

* **Daily Performance**: Standard daily metrics overview
* **Weekly Summary**: 7-day performance analysis
* **Monthly Review**: Comprehensive monthly report
* **Conversion Analysis**: Focus on conversion metrics
* **NPS Analysis**: Customer satisfaction report

### Custom Templates

Create and save your own report configurations:

```typescript theme={null}
interface ReportTemplate {
  id: string;
  name: string;
  description: string;
  filters: ReportFilters;
}
```

## Status Distribution

Understand call outcomes with status distribution analysis:

* **Completion Status**: Breakdown of finished, ongoing, and failed calls
* **Contact Results**: Distribution of answered, missed, and unreachable calls
* **Percentage Analysis**: Visual representation of status proportions

Common statuses include:

* `closed`: Successfully finished calls
* `open`: Currently ongoing calls
* `no-answer`: Unanswered calls
* `voicemail`: Calls reaching voicemail
* `failed`: Technical failures
* `busy`: Busy line encounters

## Best Practices

### Effective Reporting

<Info>
  For optimal insights, use date ranges that provide sufficient data while remaining focused on your analysis goals.
</Info>

1. **Regular Monitoring**: Generate weekly reports to track performance trends
2. **Comparative Analysis**: Compare different time periods to identify improvements
3. **Agent Benchmarking**: Compare agent performance to identify best practices
4. **Seasonal Adjustments**: Account for seasonal variations in your analysis

### Data Interpretation

* **Look for Patterns**: Identify recurring trends in daily and hourly data
* **Context Matters**: Consider external factors affecting call performance
* **Actionable Insights**: Focus on metrics you can improve through optimization

### Performance Optimization

Use reporting data to:

* Adjust calling schedules based on hourly success rates
* Optimize agent scripts based on conversion analysis
* Improve lead quality based on contact rate insights
* Enhance customer experience using NPS feedback

## API Integration

The Reporting Service provides programmatic access to all reporting functionality:

```typescript theme={null}
// Generate a report
const reportData = await reportingService.generateReport(filters);

// Export report data
const csvBlob = await reportingService.exportReport(reportData, 'csv');

// Get available agents
const agents = await reportingService.getAgents();

// Access report templates
const templates = await reportingService.getTemplates();
```

<Warning>
  API access requires proper authentication tokens. Ensure your integration handles token refresh for long-running processes.
</Warning>