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

# Ticket labels

> Define the topics you want to track, let the AI Agent apply them to every conversation, and filter your tickets by them

A **ticket label** is something you want to track across conversations, such as
`Angry customer` or `Churn risk`. The AI Agent reads your list and labels every
conversation against it, so you can filter, sort, and report on qualities no
other filter captures.

Labels live in one workspace. Each workspace keeps its own list and labels only
its own conversations.

<Note>
  Only **Admin** users can create, edit, or delete labels. Any agent can change
  the labels on a single conversation from the [ticket
  details](/documentation/tickets/conversation-view/ticket-details) panel.
</Note>

***

## How labeling works

The description you write is the instruction the AI Agent follows. It re-checks
the conversation against your whole list on every customer-visible message, so
labels keep up as a conversation develops.

Your decisions outrank the AI Agent's:

* A label you add by hand is never removed by the AI Agent.
* A label you remove by hand is never re-applied by the AI Agent.

A workspace with no labels is the off switch. Until you create the first label,
nothing is classified.

***

## Create a label

<Steps>
  <Step title="Open Ticket labels">
    Go to **Settings**, pick your workspace, and open the **Ticket labels** tab.
  </Step>

  <Step title="Create">
    Click **Create label**, then pick a color and enter a name.
  </Step>

  <Step title="Describe when it applies">
    Fill in **When should this label be applied?**. Write the criteria the AI
    Agent should judge the conversation on.
  </Step>

  <Step title="Test it">
    Click **Test** to try the description on real conversations before you save.
  </Step>

  <Step title="Save">
    Click **Create label**. New conversations are labeled from here on.
  </Step>
</Steps>

| Field                                  | Description                                                                         |
| :------------------------------------- | :---------------------------------------------------------------------------------- |
| **Name**                               | Shown on the conversation, in the ticket list, and in filters. Up to 64 characters. |
| **Color**                              | The chip color. Pick contrasting colors for labels you compare often.               |
| **When should this label be applied?** | The criteria the AI Agent applies. Up to 500 characters.                            |

Label names are unique within a workspace. Reusing a name tells you the name is
taken.

***

## What to put in the description

Write criteria, not a definition. "The customer expresses anger: shouting,
capital letters, insults, or threats to escalate" beats "angry customers". The
AI Agent judges the conversation against your sentence, so name the evidence you
would look for yourself.

### What the AI Agent can see

The classifier reads the conversation's whole timeline, not just the customer's
words. Anything in this table is fair game in a description.

| Signal                  | What it covers                                                                                                                   |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| **Messages**            | Customer messages, AI Agent replies, Human Agent replies, and internal notes.                                                    |
| **Tone and sentiment**  | How the customer writes: frustration, urgency, threats, praise.                                                                  |
| **Specialists**         | Which [Specialist](/documentation/behavior/specialists) handled the conversation, or that none matched.                          |
| **Actions and lookups** | Which [action](/documentation/actions/overview) ran, what it was called with, what it returned, and whether it failed.           |
| **Context variables**   | The values of your [Context Variables](/documentation/settings/context-variables) on this conversation, with their descriptions. |
| **Lifecycle events**    | Handoffs, takeovers, assignment and team changes, snoozes, channel switches, and how the conversation closed.                    |
| **Ratings**             | The customer's CSAT score and the internal [conversation rating](/documentation/tickets/conversation-rating), once they exist.   |

The classifier sees only the conversation it is labeling. It cannot read the
customer's other tickets, your reports, or anything outside the timeline.

### Examples

| Label                     | Description                                                                                                             |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
| **Angry customer**        | The customer is angry or insulting, threatens to escalate, or complains about how long this is taking.                  |
| **Churn risk**            | The customer asks to cancel, mentions moving to a competitor, or says they are done with us.                            |
| **Knowledge gap**         | The AI Agent could not answer the question, or handed off because the answer was nowhere in its knowledge.              |
| **Failed action**         | An action or lookup returned an error, or ran but did not produce what the customer was promised.                       |
| **Compensation promised** | Anyone promised the customer money back, a voucher, a discount, or a free replacement, whether or not it was processed. |
| **Repeat contact**        | The customer says they already wrote in about this, or refers to an earlier ticket that was not resolved.               |
| **VIP contact**           | The `plan` context variable is `enterprise`, or the customer identifies as a reseller or partner.                       |

<Tip>
  Label what a filter can't already tell you. Status, team, channel, assignee,
  and resolution are filters of their own, and the Specialist already records
  which flow ran. Labels earn their place on judgment calls: sentiment, intent,
  risk, and quality.
</Tip>

<Note>
  One label, one idea. `Angry customer` and `Churn risk` sample cleanly on their
  own, while a combined `Unhappy or leaving` label is hard to write criteria for
  and harder to act on.
</Note>

***

## Test a label before you save it

**Test** runs your draft against the workspace's last 25 conversations and shows
what it would have matched. Results stream in one conversation at a time:

* A green check means the label would apply.
* A grey cross means it would not.
* The eye icon opens that conversation in a new tab.

Nothing is saved by a test run, and no labels are applied to those
conversations. Test as often as you like while you refine the wording, on a new
label or an existing one.

<Note>
  Sampling calls the AI once per conversation, so a run takes a moment to
  finish. It starts only when you click **Test**, never on every keystroke.
</Note>

***

## Edit a label

Open a label from the table to change its name, color, or description. Changes
take effect on the next classification, so conversations already labeled keep
their labels until something new happens on them.

Renaming a label keeps it on every conversation that carries it. Rewriting the
description changes what it matches from that point on. It does not re-label
history.

***

## Delete a label

<Warning>
  Deleting a label removes it from every conversation that carries it, and from
  the filters of any [saved view](/documentation/tickets/saved-views) that uses
  it. A view that filtered on that label alone shows all conversations again.
  This cannot be undone.
</Warning>

The conversation history keeps the record. Timeline entries that mention the
label stay readable after it is gone.

***

## Limits

| Limit                      | Value          |
| :------------------------- | :------------- |
| Labels per workspace       | 30             |
| Labels on one conversation | 5              |
| Name length                | 64 characters  |
| Description length         | 500 characters |

The workspace limit keeps classification accurate and affordable. The whole list
travels with every conversation the AI Agent classifies, so a long list costs
more and decides less reliably.

At 30 labels, **Create label** is disabled until you delete one. On a
conversation already carrying 5 labels, the remaining labels are greyed out in
the picker, and your own choices keep their slots before the AI Agent's.

***

## Change the labels on a conversation

Open a conversation and use the **Labels** field in the details panel.

<Steps>
  <Step title="Open the picker">
    Click the **+** button next to the label chips.
  </Step>

  <Step title="Toggle labels">
    Check the labels that belong on this conversation and uncheck the ones that
    don't.
  </Step>

  <Step title="Close the picker">
    Your changes are saved when the picker closes. A session of edits becomes a
    single timeline entry, not one per label.
  </Step>
</Steps>

The conversation timeline records every change and who made it, so "AI added a
label: Churn risk" and "Nina removed a label: Churn risk" both stay visible.
That history is how you tell an AI label from a corrected one.

***

## Filter and report by label

Once a workspace has labels, they show up across the ticket list:

| Surface                | What you get                                                                                  |
| :--------------------- | :-------------------------------------------------------------------------------------------- |
| **Label filter**       | Filter the ticket list to one or more labels, or invert it to exclude them.                   |
| **Labels column**      | The labels on each conversation, shown as chips in the table.                                 |
| **Saved views**        | Save a label filter as a tab, for example a shared view of every angry customer.              |
| **AI Operator (Nova)** | Ask Nova to pull or summarize conversations by label, or to build a view that filters on one. |

<Tip>
  Pair a label filter with **Resolution status** to see how one kind of
  conversation actually ends. A label the AI Agent rarely resolves is usually
  pointing at a knowledge gap or a missing action.
</Tip>

***

## See also

* [Tickets](/documentation/tickets/all-tickets): filtering, columns, and search
  on the ticket table
* [Saved views](/documentation/tickets/saved-views): save a label filter as a
  reusable tab
* [Ticket details](/documentation/tickets/conversation-view/ticket-details): the
  panel where agents change labels
* [Workspace settings](/documentation/workspaces/workspace-settings): the other
  tabs in the same place