Analytics & Insights

Access comprehensive analytics and insights on your call data, including topics and sentiments.

Overview

The Insights API provides:

Call analytics and statistics
Available topics and sentiments
Filterable transcript data
Trend analysis capabilities
Performance metrics

Getting Insights Data

Get Available Topics

Retrieve all available topics for filtering and analysis:

curl -X GET "https://api.example.com/api/v1/insights/topics" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "topics": [
    {
      "id": 1,
      "name": "Billing",
      "color": "#2196F3",
      "description": "Billing and payment-related inquiries"
    },
    {
      "id": 2,
      "name": "Technical Support",
      "color": "#FF9800",
      "description": "Technical issues and troubleshooting"
    },
    {
      "id": 3,
      "name": "Account Management",
      "color": "#4CAF50",
      "description": "Account settings and profile management"
    },
    {
      "id": 4,
      "name": "Cancellation",
      "color": "#F44336",
      "description": "Service cancellation requests"
    },
    {
      "id": 5,
      "name": "Product Inquiry",
      "color": "#9C27B0",
      "description": "General product information questions"
    }
  ]
}

Get Available Sentiments

Retrieve all available sentiment classifications:

curl -X GET "https://api.example.com/api/v1/insights/sentiments" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "sentiments": [
    {
      "id": 1,
      "name": "Positive",
      "color": "#4CAF50",
      "description": "Customer satisfied with interaction"
    },
    {
      "id": 2,
      "name": "Negative",
      "color": "#F44336",
      "description": "Customer dissatisfied or upset"
    },
    {
      "id": 3,
      "name": "Neutral",
      "color": "#9E9E9E",
      "description": "No clear emotional expression"
    },
    {
      "id": 4,
      "name": "Mixed",
      "color": "#FF9800",
      "description": "Mixed or conflicting sentiments"
    }
  ]
}

Getting Call Insights

Insights Endpoint

curl -X GET "https://api.example.com/api/v1/insights?Page=1&Rows=50&DateFrom=2025-11-01&DateTo=2025-11-30" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Description
Page	integer	Page number (1-indexed)
Rows	integer	Number of rows per page (max: 100)
DateFrom	string	Start date (ISO 8601 format)
DateTo	string	End date (ISO 8601 format)

Response Structure

{
  "page": 1,
  "totalRows": 245,
  "totalPages": 5,
  "data": [
    {
      "id": 123456,
      "date": "2025-11-28T10:00:00Z",
      "topic": "Billing",
      "sentiment": "Positive",
      "score": 95.5,
      "duration": 180,
      "status": "Processed"
    }
  ]
}

Analytics Examples

Python Analytics Client

import requests
from datetime import datetime, timedelta

class AnalyticsClient:
    def __init__(self, api_base, token):
        self.api_base = api_base
        self.headers = {"Authorization": f"Bearer {token}"}
    
    def get_topics(self):
        """Get available topics"""
        response = requests.get(
            f"{self.api_base}/api/v1/insights/topics",
            headers=self.headers
        )
        return response.json()['topics']
    
    def get_sentiments(self):
        """Get available sentiments"""
        response = requests.get(
            f"{self.api_base}/api/v1/insights/sentiments",
            headers=self.headers
        )
        return response.json()['sentiments']
    
    def get_insights(self, date_from, date_to, page=1, rows=100):
        """Get insights for date range"""
        response = requests.get(
            f"{self.api_base}/api/v1/insights",
            headers=self.headers,
            params={
                'DateFrom': date_from.isoformat(),
                'DateTo': date_to.isoformat(),
                'Page': page,
                'Rows': rows
            }
        )
        return response.json()
    
    def get_topic_distribution(self, date_from, date_to):
        """Get distribution of topics"""
        insights = self.get_insights(date_from, date_to, rows=1000)
        topics = {}
        
        for item in insights.get('data', []):
            topic = item.get('topic', 'Unknown')
            topics[topic] = topics.get(topic, 0) + 1
        
        return topics
    
    def get_sentiment_distribution(self, date_from, date_to):
        """Get distribution of sentiments"""
        insights = self.get_insights(date_from, date_to, rows=1000)
        sentiments = {}
        
        for item in insights.get('data', []):
            sentiment = item.get('sentiment', 'Unknown')
            sentiments[sentiment] = sentiments.get(sentiment, 0) + 1
        
        return sentiments
    
    def get_average_score(self, date_from, date_to):
        """Get average quality score"""
        insights = self.get_insights(date_from, date_to, rows=1000)
        scores = [item.get('score', 0) for item in insights.get('data', [])]
        
        return sum(scores) / len(scores) if scores else 0

# Usage
analytics = AnalyticsClient("https://api.example.com", "your_token")

# Get available options
topics = analytics.get_topics()
sentiments = analytics.get_sentiments()

print("Available Topics:", [t['name'] for t in topics])
print("Available Sentiments:", [s['name'] for s in sentiments])

# Get insights for last 30 days
today = datetime.now()
last_month = today - timedelta(days=30)

topic_dist = analytics.get_topic_distribution(last_month, today)
sentiment_dist = analytics.get_sentiment_distribution(last_month, today)
avg_score = analytics.get_average_score(last_month, today)

print("Topic Distribution:", topic_dist)
print("Sentiment Distribution:", sentiment_dist)
print("Average Quality Score:", avg_score)

Reporting

Generate Daily Report

def generate_daily_report(date, api_token):
    """Generate daily analytics report"""
    analytics = AnalyticsClient("https://api.example.com", api_token)
    
    date_from = datetime.combine(date, datetime.min.time())
    date_to = datetime.combine(date, datetime.max.time())
    
    insights = analytics.get_insights(date_from, date_to, rows=1000)
    
    report = {
        'date': date.isoformat(),
        'total_calls': len(insights.get('data', [])),
        'topics': analytics.get_topic_distribution(date_from, date_to),
        'sentiments': analytics.get_sentiment_distribution(date_from, date_to),
        'average_score': analytics.get_average_score(date_from, date_to),
        'average_duration': sum(
            item.get('duration', 0) for item in insights.get('data', [])
        ) / len(insights.get('data', [])) if insights.get('data') else 0
    }
    
    return report

Dashboard Integration

Real-Time Dashboard Metrics

class DashboardMetrics:
    def __init__(self, api_base, token):
        self.analytics = AnalyticsClient(api_base, token)
    
    def get_daily_metrics(self):
        """Get today's metrics"""
        today = datetime.now().date()
        return {
            'daily_report': generate_daily_report(today, self.api_base),
            'timestamp': datetime.now().isoformat()
        }
    
    def get_weekly_metrics(self):
        """Get this week's metrics"""
        today = datetime.now().date()
        week_ago = today - timedelta(days=7)
        
        return {
            'date_range': f"{week_ago} to {today}",
            'topics': self.analytics.get_topic_distribution(week_ago, today),
            'sentiments': self.analytics.get_sentiment_distribution(week_ago, today),
            'average_score': self.analytics.get_average_score(week_ago, today)
        }
    
    def get_monthly_metrics(self):
        """Get this month's metrics"""
        today = datetime.now().date()
        month_ago = today - timedelta(days=30)
        
        return {
            'date_range': f"{month_ago} to {today}",
            'topics': self.analytics.get_topic_distribution(month_ago, today),
            'sentiments': self.analytics.get_sentiment_distribution(month_ago, today),
            'average_score': self.analytics.get_average_score(month_ago, today)
        }

Visualization Examples

Topic Distribution (Last 7 Days)

Billing:             ████████░░ 32%
Technical Support:   ██████░░░░ 24%
Account Management:  █████░░░░░ 20%
Cancellation:        ███░░░░░░░ 12%
Product Inquiry:     ██░░░░░░░░ 8%
Other:               ░░░░░░░░░░ 4%

Sentiment Trend (Last 30 Days)

Week 1:  Positive: 45% | Negative: 15% | Neutral: 35% | Mixed: 5%
Week 2:  Positive: 48% | Negative: 12% | Neutral: 35% | Mixed: 5%
Week 3:  Positive: 52% | Negative: 10% | Neutral: 33% | Mixed: 5%
Week 4:  Positive: 50% | Negative: 11% | Neutral: 34% | Mixed: 5%

Advanced Analytics

Quality Score Trends

def get_quality_trend(date_from, date_to, api_token):
    """Get quality score trend over time"""
    analytics = AnalyticsClient("https://api.example.com", api_token)
    insights = analytics.get_insights(date_from, date_to, rows=10000)
    
    daily_scores = {}
    for item in insights.get('data', []):
        date = item.get('date', '').split('T')[0]
        score = item.get('score', 0)
        
        if date not in daily_scores:
            daily_scores[date] = []
        daily_scores[date].append(score)
    
    # Calculate daily averages
    trend = {}
    for date, scores in daily_scores.items():
        trend[date] = sum(scores) / len(scores)
    
    return trend

Topic Trend Analysis

def analyze_topic_trends(date_from, date_to, api_token):
    """Analyze how topics are trending"""
    analytics = AnalyticsClient("https://api.example.com", api_token)
    
    # Get current period
    current = analytics.get_topic_distribution(date_from, date_to)
    
    # Get previous period
    period_length = (date_to - date_from).days
    prev_from = date_from - timedelta(days=period_length)
    prev_to = date_from
    previous = analytics.get_topic_distribution(prev_from, prev_to)
    
    # Calculate trends
    trends = {}
    for topic, count in current.items():
        prev_count = previous.get(topic, 0)
        change = count - prev_count
        pct_change = (change / prev_count * 100) if prev_count > 0 else 0
        
        trends[topic] = {
            'current': count,
            'previous': prev_count,
            'change': change,
            'percent_change': pct_change,
            'trend': '↑' if change > 0 else '↓' if change < 0 else '→'
        }
    
    return trends

Best Practices

1. Regular Monitoring

Check daily metrics
Track weekly trends
Review monthly reports
Alert on anomalies

2. Data Analysis

Analyze sentiment trends
Track topic distribution
Monitor quality scores
Compare periods

3. Action Planning

Use insights for strategy
Identify improvement areas
Train based on trends
Measure impact

4. Reporting

Generate regular reports
Share with stakeholders
Track KPIs
Demonstrate ROI

Troubleshooting

No Data Returned

Check date range
Verify authentication
Ensure data exists for dates
Try broader date range

Inconsistent Data

Verify data integrity
Check for duplicates
Confirm filtering parameters
Review data sources

Performance Issues

Reduce row limit
Narrow date range
Use pagination
Cache results

Next Steps

Speech-to-Text - Get started with transcription
Audio Intelligence - Extract insights
Health Check - Monitor system status
API Reference - Complete documentation

Overview​

Getting Insights Data​

Get Available Topics​

Get Available Sentiments​

Getting Call Insights​

Insights Endpoint​

Query Parameters​

Response Structure​

Analytics Examples​

Python Analytics Client​

Reporting​

Generate Daily Report​

Dashboard Integration​

Real-Time Dashboard Metrics​

Visualization Examples​

Topic Distribution (Last 7 Days)​

Sentiment Trend (Last 30 Days)​

Advanced Analytics​

Quality Score Trends​

Topic Trend Analysis​

Best Practices​

1. Regular Monitoring​

2. Data Analysis​

3. Action Planning​

4. Reporting​

Troubleshooting​

No Data Returned​

Inconsistent Data​

Performance Issues​

Next Steps​