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

# Session tags and auto-tagging

> Build your tag list in categories, let auto-tagging label sessions from category descriptions, sync tags to your helpdesk, and tag sessions by hand.

Tags say what a session is about, such as *Refund request* or *Login issue*, so you can filter, group, export and automate on them. You define the list once under **Tagging**, and both agents and auto-tagging pick from it. A short list people agree on beats a long one nobody remembers.

> [!NOTE]
>
> **Settings → Tagging** in your [OpenCX dashboard](https://platform.open.cx/settings/tags). Managing tags, categories, and the automation switches requires the **Tags** permission under **Settings** in **Settings → Roles**. Adding or removing tags on a session requires permission to update sessions.

## How categories guide auto-tagging

Tags live in categories. A tag without a category appears under **Uncategorized**.

| Item | Fields | What the description is for |
| - | - | - |
| Category | **Name**, **Description** (both required) | Tells auto-tagging when the tags in this category apply. When you use categories, auto-tagging first decides which categories fit the session, then picks tags from those categories and from **Uncategorized**. |
| Tag | **Tag Name**, **Description** (up to 160 characters), **Category**, **Exclude from auto-tagging** | A short hint about when to pick this specific tag. |

Write descriptions in your customers' words: what they ask about, not your internal team names. Tag and category names cannot contain double quotes, backslashes, or line breaks.

## Create categories and tags

![Adding the tag Partial refund with a description to the Billing category in Settings, Tagging](https://mintcdn.com/openchat/hiyaCL2S28Hya6Q7/images/ticketing/tag-create.gif?s=6842c8f6229612de7e53c1bd3a6f4d56)

Add a tag with a description inside the Billing category, and it appears among Billing's tags.

**1. Create a category**

On [Settings → Tagging](https://platform.open.cx/settings/tags), click **New category**. Enter a **Name**, for example *Billing*, and a **Description** of what the category covers, then click **Create category**.

**2. Add tags to it**

Open the category's menu and choose **Add tag**, or click **Add tag** inside the category. Enter a **Tag Name** and an optional **Description**, then click **Add tag**.

**3. Keep manual-only tags out of auto-tagging**

Turn on **Exclude from auto-tagging** for a tag that only an agent or a workflow should apply.

Use the search box above the list to find tags by name or description.

## Turn on auto-tagging

![Turning on the Auto-tagging switch on the Tagging settings page](https://mintcdn.com/openchat/hiyaCL2S28Hya6Q7/images/ticketing/auto-tagging-on.gif?s=a23e53a496719e212da62fba1e970b4e)

Switch on Auto-tagging under Automation and OpenCX confirms it is enabled.

Under **Automation**, the **Auto-tagging** switch tags sessions automatically, guided by each category's description. It is on for new workspaces. Auto-tagging only adds tags; it never removes a tag an agent or workflow applied, and it skips tags marked **Exclude from auto-tagging**.

With **Auto-tagging** on, OpenCX tags a session when:

* The AI resolves it, or the customer confirms it is resolved.
* The customer ends it from the widget.
* OpenCX resolves it automatically after inactivity.
* A workflow closes it with the **Close Ticket** action and **Resolved** on.
* The linked conversation is closed in Intercom.
* A phone call on the session ends.

When the AI hands a session off to your team, OpenCX also tags it at handoff, whether or not **Auto-tagging** is on.

> [!NOTE]
>
> Resolving a session from the inbox status menu does not run auto-tagging. To tag those sessions too, add the **Auto Tag Ticket** action to a workflow. It applies the most relevant tag, or the **Fallback Tag** you choose when none fits.

## Sync tags to your helpdesk

When your ticketing system is Zendesk, Intercom, or Infobip, **Automation** also shows **Sync tags to \[system]**. Turn it on to send tags to the linked ticket or conversation when they are added to a session. It is off by default. In Zendesk, OpenCX adds its tags and leaves the ticket's other tags in place.

## Add or remove tags on a session

**1. Open the session**

In the [inbox](https://platform.open.cx/inbox), open the session and find the **Session Tags** card in the sidebar.

**2. Add a tag**

Click **+**, search, and pick a tag. Tags already on the session are hidden from the list. Only tags defined under **Settings → Tagging** can be added; **Manage tags** opens that page.

**3. Remove a tag**

Click the **x** on the tag.

Workflows can do the same with **Tag Ticket**, **Remove Tag from Ticket**, **Get Ticket Tags**, and **Auto Tag Ticket**. The **Tag Added to Ticket** trigger starts a workflow when a tag lands on a session.

## Find and report on tagged sessions

* Add the **Tag** filter in the inbox and save it as a view.
* In **Filters → Group by**, choose **Tags**. A session appears under each of its tags; sessions without tags appear under **Untagged**.
* Include the **Session Tags** column in [Reports → Data Export](https://platform.open.cx/reports/data-export).

## Rename or delete tags and categories

* **Rename a tag:** editing the name replaces the old tag with a new one. Sessions already tagged keep the old name.
* **Delete a tag:** sessions already tagged keep it, but it can no longer be applied. This cannot be undone.
* **Delete a category:** its tags move to **Uncategorized**.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| A tag is never applied automatically | **Exclude from auto-tagging** is on, the session was resolved from the inbox, or **Auto-tagging** is off. | Check the tag and the switch, or add **Auto Tag Ticket** to a workflow. |
| The session tag picker says *No tags defined yet.* | No tags exist under **Settings → Tagging**. | Create categories and tags first. |
| No **Sync tags to** switch | Your ticketing system is not Zendesk, Intercom, or Infobip. | Tags stay in OpenCX; use workflows to pass them on. |
| *Tag name cannot contain double-quotes or backslashes* | The name includes a forbidden character. | Remove double quotes, backslashes, and line breaks. |

***

## Related Documentation

> [card] [Inbox](https://docs.open.cx/inbox/intro.md)
>
> Filter and group sessions by tag.

> [card] [Custom Statuses](https://docs.open.cx/ticketing/custom-statuses.md)
>
> Track where a session stands.

> [card] [Zendesk Ticketing](https://docs.open.cx/integrations/zendesk/ticketing-api.md)
>
> Tags OpenCX writes to Zendesk tickets.

> [card] [Tags API](https://docs.open.cx/api-reference/tags/index.md)
>
> Manage tags and auto-tagging programmatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.