Skip to main content
Labels give you complete control over how you categorize and organize your botBrains data. While topics automatically cluster conversations by content, labels let you add your own business logic - marking conversations for review, tracking customer segments, flagging quality examples, or building custom workflows. Think of labels as your team’s shared organizational system that adapts to exactly how you work.

​
Why Labels Matter

Manual categorization might seem low-tech compared to AI-powered topic detection, but labels solve problems that automation can’t:
  • Quality assurance workflows - Mark conversations for review, training, or escalation
  • Team coordination - Track who’s responsible or what action is needed
  • Customer segmentation - Tag VIP customers, enterprise accounts, or special cases
  • Knowledge curation - Flag excellent examples to share with your team
  • Bug tracking - Identify and categorize product issues reported through support
  • Compliance organization - Mark conversations requiring legal review or data export
The most effective teams combine automatic topics (for content patterns) with manual labels (for workflow states). Topics show what customers ask about; labels show what you’re doing about it.

​
Understanding Label Basics

Labels are simple name tags you can attach to conversations, messages, or users. Each label has:
  • Name - A short identifier (e.g., “Needs Review”, “VIP Customer”, “Bug Report”)
  • Entity type - What kind of thing it’s attached to (conversation, message, or user)
  • Usage count - How many times this label has been applied
Labels are project-specific, meaning each project has its own set of labels independent from others.

​
Labels vs. Topics

It’s important to understand when to use each: Topics (Automatic)
  • AI-generated clusters of similar conversations
  • Based on semantic content similarity
  • Updates automatically as patterns emerge
  • Best for: Understanding what customers are asking about
  • Example: “Billing Questions”, “API Integration”, “Shipping Delays”
Labels (Manual)
  • Human-applied tags for organization
  • Based on your business needs and workflows
  • Created and applied by your team
  • Best for: Workflow states, priority, quality markers
  • Example: “Review: Alice”, “Escalate to Engineering”, “Training Example”
Using Them Together 
Scenario: Customer asks about API authentication (automatic topic)
Actions:
1. TopicAI assigns topic: "API Integration"
2. You review and find their use case is unique
3. You add labels: "Feature Request" + "Enterprise Customer"
4. Later you add: "Discussed with Engineering"
5. After fix: "Fixed in v2.4"

Result: Topic shows what they asked, labels show your team's response journey
You can filter conversations by both topics and labels simultaneously, creating powerful segments like “All VIP customers asking about Billing in the last 30 days.”

​
Creating and Applying Labels

Labels are created on-the-fly as you apply them. There’s no separate “create label” step - just start typing a label name and it’s added to your project.

​
Applying Labels to Conversations

From Conversation List
  1. Navigate to Analyze → Conversations
  2. Hover over any conversation - a selection circle appears
  3. Click to select one or multiple conversations
  4. Click the label icon in the toolbar that appears at the bottom
  5. Type a label name or select from existing labels
  6. Press Enter or click to apply
From Conversation Detail Page
  1. Open any conversation by clicking it
  2. Look for the right sidebar showing user information
  3. Find the “Labels” section
  4. Click the tag icon or “Add label” button
  5. Search for an existing label or type a new one
  6. Select to apply
Quick Keyboard Workflow While viewing a conversation:
  1. Click the tag icon in the labels section
  2. Start typing immediately (focus is automatic)
  3. Use arrow keys to navigate suggestions
  4. Press Enter to apply and close
The label appears immediately and is saved automatically.

​
Applying Labels to Messages

Individual messages within conversations can also be labeled:
  1. Open a conversation detail page
  2. Find the specific message you want to label
  3. Hover over the message to reveal actions
  4. Click the tag icon for that message
  5. Apply or create a label
Why label individual messages?
  • Flag specific AI responses as training examples
  • Mark questions that revealed knowledge gaps
  • Identify particular user statements requiring follow-up
  • Track which responses used specific tools or knowledge sources

​
Applying Labels to Users

Track user-level attributes across all their conversations:
  1. Navigate to a user profile page
  2. Find the labels section in the user details
  3. Apply labels like “VIP”, “Beta Tester”, “Enterprise”
User labels automatically appear in all conversations with that user, helping you provide appropriate service levels.

​
Creating New Labels Inline

The label picker intelligently suggests creating new labels: Auto-creation
  • Type a label name that doesn’t exist yet
  • The system shows “Create [your label name]” option
  • Click or press Enter to create and apply
  • The label is now available for future use
Label name best practices
  • Use clear, descriptive names: “Needs Engineering Review” not “NER”
  • Capitalize consistently: “Bug Report” or “bug report” (pick one style)
  • Use prefixes for organization: “Review: Alice”, “Review: Bob”
  • Keep names under 30 characters for readability
  • Avoid special characters that might cause filtering issues
Label names are case-insensitive for matching but preserve your capitalization. “VIP Customer” and “vip customer” are treated as the same label, but the display will use whichever capitalization was created first.

​
Using Label Suggestions

The label picker shows smart suggestions based on your usage patterns: Assigned Labels (Top section)
  • Labels already applied to this conversation/message/user
  • Click to unassign (remove the label)
  • Shown with a checkmark indicator
Suggestions (Middle section)
  • Labels you’ve used on similar entities in this project
  • Sorted by usage count (most popular first)
  • Shows usage count next to each label
  • Click to assign
Create New (Bottom section)
  • Appears when your search doesn’t match existing labels
  • Creates and assigns in one action
Search Filtering
  • Type to filter the suggestion list
  • Matches partial names: “rev” shows “Needs Review”
  • Case-insensitive search
  • Press Enter to assign first match or create new

​
Filtering by Labels

Labels unlock powerful filtering across the platform.

​
Conversation Filter

Navigate to Analyze → Conversations and click the “Labels” filter button. Include Mode (Has Labels)
  • Show only conversations with specific labels
  • Select multiple labels for “OR” logic (has any of these)
  • Example: Include “Bug Report” OR “Feature Request”
  • Result: Conversations tagged with either label
Exclude Mode (Does Not Have Labels)
  • Hide conversations with specific labels
  • Useful for filtering out processed items
  • Example: Exclude “Already Reviewed”
  • Result: Only shows conversations not yet reviewed
Combining Both Modes
  • Use include and exclude simultaneously
  • Example: Include “Needs Review” + Exclude “Assigned: Alice”
  • Result: Things needing review that aren’t assigned to Alice
Three-State Cycle Each label in the filter has three states:
  1. Unselected (gray) - No filtering on this label
  2. Has (green plus icon) - Must have this label
  3. Not (red minus icon) - Must not have this label
Click a label repeatedly to cycle through states, or use the plus/minus buttons directly.

​
Label Filter Best Practices

Workflow states 
Create labels for each stage:
- "Needs Review"
- "In Progress"
- "Reviewed"
- "Closed"

Filter: Include "Needs Review" + Exclude "Closed"
Result: Active items requiring attention
Team assignments 
Create labels per team member:
- "Review: Alice"
- "Review: Bob"
- "Review: Charlie"

Filter: Include "Review: Alice"
Result: Alice's review queue
Priority tracking 
Create priority labels:
- "Priority: Critical"
- "Priority: High"
- "Priority: Low"

Filter: Include "Priority: Critical" + Status "Unresolved"
Result: Urgent issues needing immediate action
Customer segments 
Create segment labels:
- "Enterprise"
- "SMB"
- "Free Plan"

Filter: Include "Enterprise" + Rating 1-2 (Poor)
Result: Unhappy enterprise customers requiring attention

​
Managing Labels

View and manage all labels from one central location.

​
Accessing the Labels Page

Navigate to Settings → Labels to see your complete label inventory. The labels page displays:
  • Label name - With visual badge
  • Usage count - How many times it’s currently applied
  • Actions - Delete option
Labels are sorted by usage count (most used first) to help you understand which labels are most valuable to your workflow.

​
Viewing Label Usage

Click the usage count to navigate to a filtered view of all entities with that label. This helps you:
  • Review everything tagged with a specific label
  • Audit label usage for consistency
  • Clean up outdated labels by reviewing tagged items
  • Verify labels are being used as intended

​
Deleting Labels

Remove labels that are no longer needed:
  1. Navigate to Settings → Labels
  2. Find the label you want to remove
  3. Click the delete (trash) icon
  4. Review the confirmation dialog showing current usage count
  5. Confirm deletion
What happens when you delete:
  • All instances of the label are removed from conversations, messages, and users
  • The label name becomes available to use again
  • This action cannot be undone
  • Currently filtered views using this label will update immediately
Deleting a label removes it from all entities in your project. If a label has 50 conversations tagged, all 50 will lose that label. Make sure you export data or review tagged items before deleting if you need to preserve the categorization.
When to delete labels:
  • Typo or duplicate labels (use one consistent version)
  • Temporary tracking that’s no longer relevant
  • Abandoned workflow states you’re not using
  • Testing labels that shouldn’t be in production
  • Consolidating similar labels (delete before recreating with better name)

​
Label Organization Strategies

Effective label systems evolve from simple to sophisticated as your needs grow. Here are proven patterns:

​
Simple Workflow States

Start with basic states if you’re just beginning: 
Labels:
- "To Review"
- "Reviewed"
Usage:
  • Apply “To Review” to conversations that need attention
  • Apply “Reviewed” after handling
  • Filter to “To Review” + Exclude “Reviewed” to see queue
Graduating to next level: Add assignment when team grows to 3+ people.

​
Team Assignment System

Track who’s responsible for reviewing or handling each conversation: 
Labels:
- "Assigned: [Name]" for each team member
- Or: "Review: [Name]"
- Or: "Owner: [Name]"
Usage:
  • Weekly review: Team lead assigns labels to distribute work
  • Filter: Each person sees only their assigned conversations
  • Bulk operations: Select 10 conversations, assign all to one person
Graduating to next level: Add status labels to track progress on assignments.

​
Multi-Stage Workflow

Complex processes with multiple steps: 
Labels:
- "Stage 1: Triage"
- "Stage 2: Investigation"
- "Stage 3: Implementation"
- "Stage 4: Verification"
- "Stage 5: Closed"
Usage:
  • Apply initial stage label when issue identified
  • Update label as work progresses through stages
  • Filter to each stage to see current pipeline
  • Remove previous stage when adding new one (or keep history)
Pro tip: Use label names that sort naturally (“1:”, “2:”, etc.)

​
Priority Matrix

Categorize by urgency and importance: 
Labels:
- "Priority 1: Critical"
- "Priority 2: High"
- "Priority 3: Medium"
- "Priority 4: Low"
Combined with:
  • Topics (what it’s about)
  • Status (resolved/unresolved)
  • Customer segment labels
Filter example: 
Include: "Priority 1: Critical" + "Enterprise"
Status: Unresolved
Result: Critical issues from paying customers

​
Quality Assurance System

Track conversation quality and use for training: 
Labels:
- "QA: Excellent Example"
- "QA: Needs Improvement"
- "QA: Training Material"
- "QA: Edge Case"
- "QA: Policy Violation"
Usage:
  • Weekly QA: Review 20 random conversations
  • Apply QA labels based on quality assessment
  • Filter “QA: Excellent Example” to find onboarding materials
  • Filter “QA: Needs Improvement” to find knowledge gaps
  • Export “QA: Training Material” conversations for team learning

​
Bug and Feature Tracking

Connect support conversations to product development: 
Labels:
- "Bug: Confirmed"
- "Bug: Cannot Reproduce"
- "Bug: Fixed in [Version]"
- "Feature Request"
- "Feature: Under Consideration"
- "Feature: Implemented"
Workflow:
  1. Customer reports issue → Apply “Bug: Confirmed”
  2. Engineering investigates → Update with findings
  3. Fix deployed → Change to “Bug: Fixed in v2.4”
  4. Use filter to find all bugs fixed in specific release
Integration: Export conversations with these labels to your issue tracker for detailed analysis.

​
Customer Segment Tracking

Provide differentiated service levels: 
Labels:
- "Segment: Enterprise"
- "Segment: SMB"
- "Segment: Free"
- "Customer: VIP"
- "Customer: Beta Tester"
- "Customer: Churned"
Usage:
  • Apply automatically based on user properties
  • Combine with involvement filters to track automation rates by segment
  • Filter to “Segment: Enterprise” + Low CSAT to catch at-risk accounts
  • Review “Customer: Beta Tester” conversations for product feedback
Track conversations requiring special handling: 
Labels:
- "Legal: Review Required"
- "Legal: Approved"
- "Compliance: GDPR Request"
- "Compliance: Data Export Needed"
- "Sensitive: Confidential"
Workflow:
  1. Identify conversations with legal implications
  2. Apply appropriate label
  3. Legal team filters to “Legal: Review Required”
  4. After review, update to “Legal: Approved”
  5. Use for audit trails and compliance reporting
Combine label systems! Use workflow states + priority + customer segment together. Example: “Review: Alice” + “Priority 1: Critical” + “Segment: Enterprise” creates a very specific, actionable queue.

​
Batch Label Operations

Efficiently apply or remove labels across multiple items at once.

​
Selecting Multiple Conversations

Method 1: Click to select
  1. Navigate to conversation list
  2. Hover over a conversation card
  3. Click the selection circle that appears
  4. Repeat for other conversations
Method 2: Selection mode
  1. Click one selection circle
  2. All cards now show selection circles
  3. Click multiple cards to select
  4. Count shown in bottom toolbar
Method 3: Filter then select
  1. Apply filters to narrow to target set
  2. Select specific conversations from filtered results
  3. Apply labels to just those selected items

​
Applying Labels in Batch

With conversations selected:
  1. Click the “Labels” button in the bottom toolbar
  2. Select or create label(s) to apply
  3. Click “Apply” or press Enter
  4. Labels added to all selected conversations instantly
  5. Selection clears automatically
Use cases:
  • Weekly review: Select 20 conversations, apply “Reviewed by [Name]”
  • Bug triage: Select all conversations about same issue, apply “Bug #1234”
  • Team assignment: Select subset, apply assignment labels
  • Quality sampling: Select examples, apply “QA: Excellent Example”

​
Removing Labels in Batch

With conversations selected:
  1. Click the “Remove Labels” button in toolbar
  2. Select which label(s) to remove
  3. Confirm removal
  4. Labels removed from all selected conversations
Use cases:
  • Clearing workflow states after processing
  • Removing outdated labels in bulk
  • Correcting labeling mistakes
  • Archiving old tracking labels
Combine filters with batch operations for powerful workflows. Example: Filter to “Status: Resolved” + “To Review” + “Last 7 days”, select all, add “Reviewed”, remove “To Review”. This marks all resolved conversations from the week as reviewed in seconds.

​
Advanced Label Patterns

​
Progressive Disclosure

Use labels to create a funnel from broad to specific: 
Level 1: "Needs Attention" (initial triage)
↓
Level 2: "Type: Bug" or "Type: Question" (categorize)
↓
Level 3: "Bug: Critical" or "Bug: Minor" (prioritize)
↓
Level 4: "Assigned: Engineering" (route)
↓
Level 5: "Fixed in v2.4" (resolve)
Each label adds information without removing previous context.

​
Temporary vs. Permanent Labels

Temporary Labels (remove after use)
  • “To Review”
  • “Pending Response”
  • “Blocked: Waiting on [Team]”
Remove these once action is complete. Permanent Labels (keep for history)
  • “Bug Report”
  • “Feature Request”
  • “VIP Customer”
  • “Escalated to Engineering”
Keep these for trend analysis and reporting.

​
Time-Based Labels

Track when things happened: 
Labels:
- "Week of 2024-03-01"
- "Q1 2024 Review"
- "Sprint 23"
Usage:
  • Weekly review sessions: Tag all reviewed conversations with that week
  • Compare weeks: Filter to each week label, compare metrics
  • Sprint retrospectives: Review all conversations from sprint
  • Seasonal analysis: Tag conversations during holiday period

​
Cross-Team Collaboration

When multiple teams interact with the same conversations: 
Support Team:
- "Support: Initial Response"
- "Support: Escalated"

Product Team:
- "Product: Feature Request"
- "Product: Added to Roadmap"

Engineering:
- "Eng: Bug Confirmed"
- "Eng: Fix Deployed"

Success Team:
- "Success: Follow-up Scheduled"
- "Success: Customer Satisfied"
Each team adds their labels without removing others, creating complete audit trail.

​
Exporting Label Data

Labels enhance your exported data with custom categorization.

​
CSV Export with Labels

When exporting conversations:
  1. Navigate to Analyze → Conversations
  2. Apply label filters to narrow export
  3. Click “Export”
  4. Select CSV format
  5. Labels included as comma-separated column
Example CSV row: 
conversation_id,created_at,status,labels,topic
conv_123,2024-03-15,resolved,"Bug Report,Priority 1: Critical,Fixed in v2.4",API Integration
Use exported label data for:
  • External reporting tools
  • Custom analytics in Excel/Google Sheets
  • Feeding into business intelligence platforms
  • Compliance documentation
  • Backup and archival

​
JSON Export with Labels

For programmatic analysis: 
{
  "conversation_id": "conv_123",
  "labels": [
    "Bug Report",
    "Priority 1: Critical",
    "Fixed in v2.4"
  ],
  "created_at": "2024-03-15T10:30:00Z"
}
Structured label data enables:
  • Custom dashboard creation
  • Integration with issue trackers
  • Automated reporting workflows
  • Machine learning on label patterns

​
Combining Labels with Other Features

Labels become even more powerful when combined with other botBrains features.

​
Labels + Topics

Pattern: Action on Content 
Topic: "Billing Questions" (what they asked about)
Labels: "Review: Alice" + "High Priority" (what you're doing about it)

Filter: Topic = "Billing Questions" + Label = "High Priority"
Result: Critical billing questions needing attention
Use case: Find topics that consistently require certain labels (e.g., “API Integration” always needs “Engineering Review”) and create automatic escalation rules.

​
Labels + Audiences

Create audience segments based on label patterns: Audience: VIP Customers 
Rule: Has label "VIP Customer"
AI Behavior: More formal tone, offer direct contact options
Audience: Bug Reporters 
Rule: Has label "Bug Report"
AI Behavior: Collect detailed reproduction steps, offer tracking number
This allows conversation labels to influence AI behavior in future interactions.

​
Labels + Metrics

Filter metrics dashboards by labels to analyze subsets: Example 1: QA Performance 
Filter: Label = "QA: Reviewed"
Metrics: CSAT, Resolution Rate, Involvement
Result: Understand quality of reviewed conversations
Example 2: Priority Response Time 
Filter: Label = "Priority 1: Critical"
Metrics: First Response Time, Total Duration
Result: Measure SLA compliance for critical issues
Example 3: Team Performance 
Filter: Label = "Assigned: Alice"
Compare to: Label = "Assigned: Bob"
Metrics: Resolution Rate, CSAT
Result: Compare team member effectiveness
Search for specific content within labeled conversations:
  1. Navigate to Analyze → Message Search
  2. Apply label filter
  3. Search message content
  4. Find specific phrases within categorized conversations
Example: 
Filter: Label = "Bug Report"
Search: "error code"
Result: All bug reports mentioning error codes

​
Best Practices

Follow these guidelines to build effective label systems:

​
Start Simple, Evolve Gradually

Week 1-2: Basic States 
Labels:
- "To Review"
- "Reviewed"
Month 1: Add Assignment 
Labels:
- "To Review"
- "Review: [Name]"
- "Reviewed"
Month 2-3: Add Priority 
Labels:
- "Priority: High"
- "Priority: Normal"
- "To Review"
- "Review: [Name]"
- "Reviewed"
Month 4+: Custom Categories Add labels specific to your business needs as you discover them.

​
Document Your Label System

Create a shared document explaining:
  • What each label means
  • When to apply it
  • Who should apply it
  • What to do when you see it
Example documentation: 
Label: "Bug: Confirmed"
Meaning: Engineering verified this is a real product bug
When to apply: After engineering investigates and confirms
Who applies: Engineering team only
Next action: Apply "Bug: Fixed in [version]" when deployed
This ensures consistent usage across your team.

​
Review and Clean Regularly

Monthly label audit:
  1. Sort labels by usage count (least used first)
  2. Review labels with 0-2 uses
  3. Delete typos and duplicates
  4. Merge similar labels
  5. Archive completed temporary labels
Signs a label should be deleted:
  • Zero usage in past 90 days
  • Duplicate of another label (slight variation)
  • Temporary workflow label for completed project
  • Unclear purpose (team doesn’t remember what it’s for)

​
Use Consistent Naming Conventions

Choose a convention and stick to it: Prefixes for grouping: 
Good:
- "Review: Alice"
- "Review: Bob"
- "Priority: High"
- "Priority: Low"

Bad:
- "Alice Review"
- "Review Bob"
- "High Priority"
- "Low"
Capitalization: 
Good: "Bug Report" (consistent)
Bad: "bug Report", "Bug report", "bug report" (inconsistent)
Word count: 
Good: "Needs Engineering Review" (3-4 words)
Bad: "Needs to be reviewed by engineering team" (too long)

​
Don’t Over-Label

Warning signs you’re using too many labels:
  • More than 50 active labels in one project
  • Labels used only once or twice
  • Confusion about which label to apply
  • Labels with overlapping meanings
  • Team members creating duplicate labels
Solution: Consolidate related labels, focus on labels that drive action.

​
Combine with Filtering

Labels are most powerful when used for filtering, not just documentation: Ask yourself: “Will I filter by this label to find a specific subset of conversations?” If yes → Good label If no → Consider if you need it Good labels drive action:
  • “Needs Review” → Filter to see review queue
  • “Priority: High” → Filter to see urgent items
  • “Feature Request” → Filter to collect product feedback
Poor labels just add metadata:
  • “Interesting” → Too subjective, won’t filter effectively
  • “Conversation” → Not distinctive, applies to everything
  • “2024” → Better to use date range filter

​
Troubleshooting

​
Can’t Find a Label

Issue: Label you applied isn’t showing in filter or management page Solutions:
  1. Check you’re in the correct project
  2. Verify label was actually applied (check conversation detail)
  3. Ensure label wasn’t deleted by another team member
  4. Try refreshing the page
  5. Check if you’re searching with different capitalization

​
Label Applied to Wrong Conversations

Issue: Accidentally applied label to many conversations in batch Solutions:
  1. Filter to show only conversations with that label
  2. Select all affected conversations
  3. Use “Remove Labels” batch action
  4. Remove the incorrect label
  5. Re-apply to correct conversations if needed
Prevention: Always verify your filter settings before batch operations. Check the conversation count matches expectations.

​
Duplicate or Similar Labels

Issue: Team created multiple labels with similar names Examples:
  • “Bug Report” and “bug report”
  • “Review: Alice” and “Alice Review”
  • “High Priority” and “Priority: High”
Solutions:
  1. Decide which naming convention to keep
  2. Filter conversations by old label
  3. Note which conversations have it (or export list)
  4. Batch apply new correct label to those conversations
  5. Batch remove old label
  6. Delete old label from management page
Prevention: Document your label naming conventions and share with team.

​
Labels Not Appearing in Filters

Issue: Created labels don’t show in label filter dropdown Solutions:
  1. Refresh the page
  2. Verify labels were successfully created (check management page)
  3. Ensure labels have been applied at least once
  4. Check that filter is set to correct entity type (conversation vs message)
  5. Clear browser cache if problem persists

​
Can’t Delete Label

Issue: Delete button doesn’t work or label keeps reappearing Solutions:
  1. Ensure you have admin permissions
  2. Check if label is currently in use (might be being re-applied by automation)
  3. Refresh page and try again
  4. Check for background sync issues
  5. Contact support if issue persists

​
Next Steps

Now that you understand label organization:

Filter Conversations

Use labels to find specific conversation segments for review

Analyze Topics

Combine automatic topic detection with manual labels for powerful insights

Track Metrics

Filter metrics dashboards by labels to measure team or category performance

Search Messages

Search within labeled conversation sets to find specific content

Export Data

Export conversations with label data for external analysis
 Remember: Labels are your custom organization system. Start simple with just a few essential labels, then expand your system as patterns emerge in your workflow. The best label systems evolve naturally from your team’s actual needs, not from theoretical frameworks.