Skip to main content

Topic Detection

Automatically identify and categorize discussion topics in conversations.

Overview​

Topic Detection helps you:

  • Understand conversation subject matter
  • Categorize calls by topic
  • Track trending topics
  • Route based on conversation topics
  • Analyze topic frequency and patterns

How It Works​

SpeechLytics analyzes transcribed text to identify topics:

  1. Process transcription: Analyze conversation text
  2. Identify themes: Recognize key discussion topics
  3. Classify topics: Map to predefined or custom categories
  4. Extract keywords: Extract relevant topic indicators

Response Format​

{
  "topics": [
    {
      "title": "Billing Question",
      "description": "Customer inquired about charges on their account"
    },
    {
      "title": "Account Management",
      "description": "Discussion of account settings and preferences"
    }
  ]
}

Topic Fields​

FieldDescription
titleTopic classification name
descriptionDetailed explanation of the topic

Getting Topics​

From Transcript Status​

curl -X GET "https://api.example.com/api/v1/transcripts/123456789/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response includes:

{
  "topics": [
    {
      "title": "Payment Issue",
      "description": "Customer experiencing payment processing problems"
    }
  ]
}

Available Topics​

Retrieve all available topics:

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

Response:

{
  "topics": [
    {
      "id": 1,
      "name": "Billing",
      "color": "#2196F3"
    },
    {
      "id": 2,
      "name": "Technical Support",
      "color": "#FF9800"
    },
    {
      "id": 3,
      "name": "Account Management",
      "color": "#4CAF50"
    },
    {
      "id": 4,
      "name": "Cancellation",
      "color": "#F44336"
    },
    {
      "id": 5,
      "name": "Product Inquiry",
      "color": "#9C27B0"
    }
  ]
}

Query by Topic​

curl -X GET "https://api.example.com/api/v1/transcripts?Topic=Billing&Rows=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

  • Topic=Billing - Find billing-related calls
  • Topic=Technical Support - Find technical support calls
  • Topic=Account Management - Find account management calls
  • Multiple topics with different queries

Topic Distribution​

Analyze topic distribution across your calls:

import requests

def get_topic_distribution(token, date_from, date_to):
    """Get distribution of topics across date range"""
    headers = {"Authorization": f"Bearer {token}"}
    
    # Get available topics
    topics_response = requests.get(
        "https://api.example.com/api/v1/insights/topics",
        headers=headers
    )
    topics = topics_response.json()['topics']
    
    # Count each topic
    distribution = {}
    for topic in topics:
        search_response = requests.get(
            f"https://api.example.com/api/v1/transcripts",
            headers=headers,
            params={
                'Topic': topic['name'],
                'DateFrom': date_from,
                'DateTo': date_to,
                'Rows': 1000
            }
        )
        distribution[topic['name']] = len(search_response.json().get('data', []))
    
    return distribution

Multi-Topic Conversations​

Conversations often cover multiple topics:

{
  "topics": [
    {
      "title": "Billing Question",
      "description": "Initial inquiry about charges",
      "startTime": 0,
      "endTime": 45,
      "confidence": 0.95
    },
    {
      "title": "Product Recommendation",
      "description": "Agent suggested upgrade options",
      "startTime": 46,
      "endTime": 120,
      "confidence": 0.87
    },
    {
      "title": "Account Update",
      "description": "Customer updated payment information",
      "startTime": 121,
      "endTime": 180,
      "confidence": 0.92
    }
  ]
}

Topic-Based Analytics​

from datetime import datetime, timedelta
import requests

class TopicAnalyzer:
    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_topic_count(self, topic, days=7):
        """Get count of calls with specific topic in last N days"""
        date_from = (datetime.now() - timedelta(days=days)).isoformat()
        date_to = datetime.now().isoformat()
        
        response = requests.get(
            f"{self.api_base}/api/v1/transcripts",
            headers=self.headers,
            params={
                'Topic': topic,
                'DateFrom': date_from,
                'DateTo': date_to,
                'Rows': 1000
            }
        )
        return len(response.json().get('data', []))
    
    def get_trend_report(self, days=30):
        """Generate trend report for all topics"""
        topics = self.get_topics()
        report = {}
        
        for topic in topics:
            report[topic['name']] = {
                'count_7d': self.get_topic_count(topic['name'], 7),
                'count_30d': self.get_topic_count(topic['name'], 30),
                'color': topic['color']
            }
        
        return report

Custom Topic Categories​

Define Custom Topics​

{
  "customTopics": [
    {
      "name": "Emergency Support",
      "keywords": ["urgent", "emergency", "critical", "down"],
      "priority": "high"
    },
    {
      "name": "Feature Request",
      "keywords": ["feature", "capability", "wish", "suggest"],
      "priority": "medium"
    }
  ]
}

Topic Keyword Matching​

Topics are identified through:

  • Keyword matching: Relevant keywords in transcription
  • Semantic analysis: Meaning and context
  • Classification models: ML-based categorization
  • Pattern recognition: Common topic patterns

Use Cases​

1. Call Routing​

  • Route to specific teams based on topic
  • Automate call distribution
  • Skill-based routing

2. Quality Assurance​

  • Monitor topic-specific handling
  • Ensure proper procedures followed
  • Track resolution by topic

3. Performance Analytics​

  • Topic-specific KPIs
  • Agent specialization tracking
  • Resource allocation

4. Training & Development​

  • Identify training needs by topic
  • Create topic-specific training
  • Track competency improvement

5. Business Intelligence​

  • Track customer inquiries
  • Identify product/service issues
  • Understand market needs
  • Guide product development

Topic Confidence Scoring​

Each topic has a confidence score:

{
  "topic": "Billing Question",
  "confidence": 0.94
}
  • 0.9+: Very confident
  • 0.7-0.9: Confident
  • 0.5-0.7: Moderate confidence
  • <0.5: Low confidence (multiple possible topics)

Integration Example​

import requests
import json

class TopicRouter:
    def __init__(self, api_base, token):
        self.api_base = api_base
        self.headers = {"Authorization": f"Bearer {token}"}
        
        # Define routing rules
        self.routing_rules = {
            'Billing': 'billing_team@company.com',
            'Technical Support': 'support_team@company.com',
            'Account Management': 'account_team@company.com',
            'Cancellation': 'retention_team@company.com'
        }
    
    def route_call(self, transcript_id):
        """Route call based on detected topic"""
        # Get transcript topics
        response = requests.get(
            f"{self.api_base}/api/v1/transcripts/{transcript_id}/status",
            headers=self.headers
        )
        transcript = response.json()
        
        # Extract primary topic
        topics = transcript.get('topics', [])
        if not topics:
            return 'general_queue@company.com'
        
        primary_topic = topics[0]['title']
        
        # Route based on topic
        routing_address = self.routing_rules.get(
            primary_topic,
            'general_queue@company.com'
        )
        
        return {
            'transcript_id': transcript_id,
            'detected_topic': primary_topic,
            'routed_to': routing_address
        }

Visualization​

Topic Distribution​

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

Timeline Topics​

0-60s:   Greeting (Confidence: 100%)
60-180s: Billing Question (Confidence: 94%)
180-240s: Product Recommendation (Confidence: 87%)
240-300s: Account Update (Confidence: 92%)

Best Practices​

1. Leverage for Routing​

  • Use topic detection for intelligent call routing
  • Ensure routing rules align with business needs
  • Monitor routing accuracy

2. Quality Assurance​

  • Review topic-specific handling
  • Create topic-specific QA standards
  • Train agents on topic expertise

3. Analytics​

  • Establish baseline metrics per topic
  • Monitor trends over time
  • Identify emerging issues
  • Track resolution rates by topic

4. Continuous Improvement​

  • Use topic data for process improvement
  • Identify training opportunities
  • Update topic definitions as needed
  • Measure impact of changes

Troubleshooting​

Topic Not Detected​

  • Insufficient speech content in that area
  • Topic may not match predefined categories
  • Low confidence score
  • Check transcription accuracy

Incorrect Topic Classification​

  • Topics may overlap
  • Context-dependent language
  • Ambiguous conversations
  • Multiple concurrent topics

Missing Topics​

  • Custom topics may not be configured
  • Topic availability depends on account tier
  • Check topic list with /api/v1/insights/topics

Next Steps​