> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Topic Analyzer
> Automatically analyze and categorize conversations by topic
Topic Analyzer automatically assigns topics to conversations based on content analysis, enabling better organization and insights without manual effort.
## Overview
Topic Analyzer is an add-on that:
* **Automatically Categorizes Conversations**: Assigns relevant topics based on content
* **Enables Filtering**: Search and filter by auto-generated topics
* **Improves Analytics**: Track topic trends automatically
* **Reduces Manual Work**: No need for agents to manually categorize
## Prerequisites
### System Requirements
* AGO platform deployed
* Topic Analyzer add-on enabled
* Topics configured in Conversation Labels
### Configuration Required
* Enable in **Settings** > **Topic Analyzer**
* Configure custom instructions and settings
***
## Enabling Topic Analyzer
### Via Admin Interface
1. Navigate to **Settings** > **Topic Analyzer**
2. The page shows two tabs: **Custom Instructions** and **Settings**
3. Configure the analysis behavior using custom instructions
4. Adjust settings like maximum topics per conversation
Topic Analyzer can also be configured via API. See the [Public API v1 Reference](/api/public-api-v1) for endpoint details.
***
## How It Works
```
Conversation Message → Content Analysis → Topic Matching → Auto-Assign Topics
```
1. A conversation is completed or analyzed on demand
2. The system analyzes conversation content using AI
3. Matching topics are identified based on configured instructions
4. Topics are automatically assigned to the conversation
### Analysis Methods
| Method | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Keyword Matching** | Topics assigned when conversation content matches tag keywords (case-insensitive, whole-word matching) |
| **AI Classification** | An LLM analyzes the conversation and assigns the most relevant topics based on your custom instructions and tag descriptions |
Both methods run together. Keyword matching provides fast, predictable tagging for known terms, while AI classification catches topics that keywords might miss.
***
## Configuration
### Custom Instructions
The **Custom Instructions** tab allows you to define how the AI should analyze conversations and assign topics. Use the editor to write specific instructions that guide the topic assignment process.
You can view a diff of your changes against the saved version before saving.
### Settings
The **Settings** tab provides the following options:
| Setting | Description |
| ------------------------------------ | ------------------------------------------------- |
| **Maximum Topics per Conversation** | Limit how many topics can be assigned (1-20) |
| **Always assign at least one topic** | Verify every conversation gets at least one topic |
### Managing Topics
Topics are managed in the **Conversation Labels** page under the **Topics** tab. Each topic can have:
* A name and description
* Keywords for matching
* A parent topic for hierarchical organization
Click **Manage Topics** in the Settings tab to navigate directly to the Conversation Labels page.
***
## Running Topic Analysis
### From the Conversation Sidebar
When viewing a conversation in Chat History:
1. Open the conversation sidebar
2. Find the **Topics** section
3. Click **Run Topic Analysis** to analyze the conversation
4. Topics are automatically assigned based on the analysis
### Filtering by Topics
In Chat History, filter conversations by topic:
* Select topics in the filter panel
* Combine with other filters for targeted results
* Export filtered results
### Analytics
Topics feed the [Topics Analytics](/features/topics-analytics) dashboard tab, which shows:
* Topic distribution treemap
* Daily topic trends
* Topics by agent breakdown
* CX Score by topic (when the Thread Evaluator is enabled)
* Escalation rate per topic
***
## Practical Examples
### Example 1: Support Category Analysis
Automatically categorize support conversations:
**Topics to create:**
* `billing` - Payment, invoices, subscriptions
* `technical` - Bugs, errors, how-to questions
* `account` - Login, password, profile issues
* `feature-request` - New feature suggestions
**Result**: View your Analytics dashboard to see which categories drive the most conversations.
### Example 2: Escalation Tracking
Track conversations that require human intervention:
**Topics:**
* `escalated` - Applied when ticketing tool is used
* `frustrated-customer` - Applied by AI when sentiment is negative
* `complex-issue` - Multi-step problems requiring follow-up
### Example 3: Product-Specific Routing
Categorize conversations by product area for team assignment:
**Topics:**
* `product-a` - Questions about Product A
* `product-b` - Questions about Product B
* `integration` - Third-party integration issues
**Keyword matching:**
| Topic | Triggers when user mentions... |
| ----------- | ----------------------------------------- |
| product-a | "Product A", "feature X", "module 1" |
| product-b | "Product B", "dashboard", "reports" |
| integration | "API", "webhook", "Zapier", "integration" |
### Example 4: Hierarchical Topic Organization
Use parent topics for structured categorization:
**Parent Topics:**
* `support` (parent)
* `billing-support` (child)
* `technical-support` (child)
* `sales` (parent)
* `upsell-opportunity` (child)
* `new-lead` (child)
***
## Best Practices
| Practice | Recommendation |
| -------------- | ------------------------------------------------------- |
| **Naming** | Use lowercase with hyphens: `feature-request` |
| **Quantity** | Aim for 10-20 core topics (too many reduces usefulness) |
| **Hierarchy** | Use parent topics to group related topics |
| **Review** | Consolidate and clean up topics quarterly |
| **Monitoring** | Check topic distribution weekly for trends |
***
## Related Documentation
* [Thread Evaluator](./thread-evaluator) - Conversation quality assessment
* [CX Score](./cx-score) - Customer experience scoring
* [Conversations](/features/conversations-list) - Search and filter conversations
* [Topics Analytics](/features/topics-analytics) - View topic distribution and trends
* [Conversation Labels](/features/conversation-labels) - Manage topics and admin tags