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

# Smart tags

> Define conversation topics for Remark's AI to tag, then use the tags in the Inbox, workflows, Klaviyo, and the API.

Smart tags label conversations by topic. You describe each topic in plain language. After a conversation closes, Remark's AI reads the transcript and applies each of your tags the conversation directly addresses.

Use smart tags to find conversations in the [Inbox](/dashboard/inbox.md), start [workflows](/dashboard/workflows.md), segment shoppers in [Klaviyo](/integrations/klaviyo/overview.md), and count topics over time with the [GraphQL API](/api-reference/introduction.md#smart-tag-aggregation).

> [!NOTE]
>
> Only owners and admins can open **Settings > Smart tags** to create, edit, and delete tags. Team members with the **Conversations** permission group can view tags on conversations and filter the Inbox by them. For details, read [Team member permissions](/dashboard/team-member-permissions.md#owner-and-admin-only).

## How Remark applies smart tags

Remark tags each conversation [segment](/dashboard/inbox.md#segments) after the segment closes. When a shopper reopens a conversation, Remark tags the new segment once it closes too. Tagging covers Remark chat conversations and helpdesk tickets Remark took part in.

For each segment, Remark:

1. Reads the segment's transcript.
2. Compares the transcript with the title, description, and expressions of every active smart tag, including [global tags](#global-smart-tags).
3. Rates how directly the conversation addresses each tag.
4. Applies a tag when the shopper or the representative raises its topic with a concrete question, request, explanation, or action.

A passing mention or a related topic doesn't qualify. A segment can receive several tags or none.

Remark uses the tag definitions in place when each segment closes. When you edit or delete a tag, the change affects segments closing afterward, and past conversations keep the tags they already have.

## Tag fields

| Field | Use it for |
| - | - |
| **Title** | The label shown in the Inbox and in Klaviyo events. Each title must be unique in your workspace. You can't change a title after you create the tag. |
| **Description** | When the tag applies. Describe scenarios where the tag applies and where it doesn't. |
| **Expressions** | Optional example keywords or phrases shoppers use for the topic. |

For example, a tag for subscription cancellations could use:

```txt theme={null}
Title: Subscription cancellation

Description: The shopper asks to cancel, pause, or skip a subscription, or asks how to do it.
Doesn't apply to cancelling a one-time order or to questions about subscription pricing.

Expressions:
- I want to cancel my subscription
- How do I stop my monthly box?
- Can I skip next month's delivery?
```

## Create a smart tag

1. Open **Settings > Smart tags**.
2. Select **New smart tag**. If you have no tags yet, select **Create a smart tag**.
3. Enter a **Title**.
4. Enter a **Description**.
5. Under **Expressions**, select **Add expression** for each example phrase.
6. Select **Create smart tag**.

Remark starts applying the tag to segments closing after you create it.

## Edit or delete a smart tag

Use **Search for tags** to find a tag by title.

* To edit a tag, select **Edit smart tag** (the pencil icon). Change the **Description** or **Expressions**, then select **Save smart tag**.
* To delete a tag, select **Delete smart tag** (the trash icon). Remark deletes the tag right away, without asking for confirmation.

After you delete a tag, Remark stops applying it, and it disappears from the Inbox **Smart tags** filter. Past conversations still show the tag in their details panel. The title stays reserved, so you can't create another tag with the same title.

## Global smart tags

Tags marked **Global** come from Remark and apply to conversations in every workspace. They appear after your own tags. Select **View smart tag** (the magnifying glass icon) to read a global tag's definition. You can't edit or delete global tags.

## Where smart tags appear

| Where | What you can do |
| - | - |
| [Inbox](/dashboard/inbox.md#filter-conversations) **Smart tags** filter | Find conversations where any segment received one of the selected tags. Tags used most often in the last 90 days appear first. The filter appears once your workspace has smart tags. |
| [Inbox](/dashboard/inbox.md#details-panel) details panel | Read the tags on the conversation's most recent segment in the **Smart tags** field. Hover a tag to read its description. |
| [Workflows](/dashboard/workflows.md#triggers) | Start a workflow with the **Smart Tag Applied** event trigger each time Remark applies a tag. Available when workflows are enabled for your workspace. |
| [Klaviyo](/integrations/klaviyo/overview.md#event-and-profile-settings) | Send the **Smart tag applied** tracking event, recorded as the **Is Assigned a Remark Smart Tag** metric. Remark sends it only for shoppers whose email address it knows. |
| [GraphQL API](/api-reference/introduction.md#filter-options) | Filter conversations with `smartTagIds`, count tags with `smartTagCounts`, and list tags with `vendorSmartTags`. |

### Run a workflow for one tag

The **Smart Tag Applied** trigger fires for every tag Remark applies. Its trigger data includes `tagId`, `segmentId`, and `conversation`, which holds the conversation's `id` and `externalId`. To run a workflow for a single tag, add a condition on the tag ID to the trigger:

```txt theme={null}
data.tagId = "<tag ID>"
```

To find a tag's ID, filter the Inbox by that tag alone and copy the value after `smartTagIds=` in the page URL. You can also query `vendorSmartTags` with the [GraphQL API](/api-reference/introduction.md#list-available-smart-tags).

## Troubleshooting

### A conversation is missing a tag

Remark tags a segment only after it closes, so open conversations have no tags yet. If the segment has closed, check whether the conversation addressed the topic directly. Make the **Description** more specific, and add **Expressions** closer to how shoppers phrase the request. Your changes affect segments closing afterward.

### A tag applies to unrelated conversations

Add the cases where the tag doesn't apply to its **Description**. In the example above, the subscription cancellation tag excludes one-time order cancellations.

### Creating a tag fails with a duplicate title error

The message **A current or archived smart tag with this title already exists. Choose a different title.** means one of your current or deleted tags already uses the title. Choose a different title.

### Settings > Smart tags is missing

Only owners and admins can open the page. Ask a workspace owner or admin to create or change the tag.


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