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

# Labels

> Organize conversations, messages, and users with custom labels for quality assurance and workflow management

Labels let you add your own business logic on top of your botBrains data. While [Topics](/concepts/topics) automatically cluster conversations by content, labels are tags you apply manually or via [Triggers](/concepts/triggers) - for review workflows, customer segments, quality tracking, or anything else your team needs.

Labels are project-specific. Each label has a **name**, an **entity type** (conversation, message, or user), and a **usage count**.

## Applying Labels

You create labels on the fly - just start typing a name in the label picker and it joins your project. No separate creation step needed.

**On conversations** - open a conversation and use the label section in the right sidebar, or select one or more conversations from the [conversation list](https://platform.botbrains.io/~/conversations) and click the label icon in the bulk-action toolbar.

<img src="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/labels/conversation-label-sidebar.png?fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=3d6633781b9bd3f9a8d54576b926bd7b" alt="Label section in conversation right sidebar showing a text input field and applied labels with removal buttons" data-generation-prompt="Navigate to a conversation on platform.botbrains.io/~/conversations. Click into any conversation to open the detail view. Scroll to the right sidebar and locate the Labels section. Take a screenshot showing the label input field and any applied labels. Use 1920x1080 viewport." width="1920" height="1080" data-path="images/labels/conversation-label-sidebar.png" />

**On messages** - hover over a message in the conversation detail view and click the tag icon.

**On users** - open a user profile and apply labels like "VIP", "Beta Tester", or "Enterprise". User labels appear across all their conversations.

<Warning>
  Label names are case-insensitive for matching but preserve the original capitalization. "VIP Customer" and "vip customer" are the same label.
</Warning>

## Filtering by Labels

Use the label filter on the [conversations page](https://platform.botbrains.io/~/conversations) or in [Metrics](/concepts/metrics) to narrow your view. Each label cycles through three states:

| State      | Icon       | Effect                             |
| ---------- | ---------- | ---------------------------------- |
| Unselected | Gray       | No filtering on this label         |
| Has        | Green plus | Only show entities with this label |
| Not        | Red minus  | Hide entities with this label      |

<img src="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/labels/label-filter-states.png?fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=7602e5c4b23c4c49f1b2b4ec9f0fdda9" alt="Label filter toggle showing the three states: gray unselected, green plus for inclusion, red minus for exclusion" data-generation-prompt="Navigate to platform.botbrains.io/~/conversations. Click on the Labels filter dropdown in the top filter bar. Click labels to cycle through states (gray unselected, green include, red exclude). Show the dropdown open with labels in different states. Use 1920x1080 viewport, collapse sidebar." width="1920" height="1080" data-path="images/labels/label-filter-states.png" />

You can combine include and exclude filters. For example, include "Needs Review" and exclude "Assigned: Alice" to see unassigned review items.

## Managing Labels

Open the [labels page](https://platform.botbrains.io/~/labels) to see all labels in your project, sorted by usage count. From there you can:

* **Click a usage count** to navigate to a filtered view of all entities with that label
* **Delete a label** with the trash icon - this removes the label from all entities and cannot be undone

<img src="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/labels/labels-management-page.png?fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=ed614020d08354020100bcc9357a650f" alt="Labels management page showing a table of labels sorted by usage count with delete buttons and clickable usage numbers" data-generation-prompt="Navigate to platform.botbrains.io/~/labels. Take a screenshot of the full labels management page showing the table with at least 5-8 sample labels of varying usage counts. The table should display label names, usage counts (as clickable numbers), and delete/trash icons for each row. Use 1920x1080 viewport and collapse the sidebar for a full-width view of the table." width="1920" height="1080" data-path="images/labels/labels-management-page.png" />

<Tip>
  Use consistent naming conventions with prefixes for grouping: "Review: Alice", "Priority: High", "Bug: Confirmed". This keeps labels sortable and scannable as your system grows.
</Tip>

## Next Steps

* [Conversations](/concepts/conversations) - Filter and review labeled conversations
* [Topics](/concepts/topics) - Combine automatic topic detection with manual labels
* [Triggers](/concepts/triggers) - Assign or remove labels automatically based on rules
* [Metrics](/concepts/metrics) - Filter dashboards by labels to measure segment performance
* [Data Export](/concepts/data-export) - Export conversations with label data