Skip to main content

Custom tags

You can configure custom tags to be assigned automatically to your conversations: you define a tag with a description of when it applies, and Kapa classifies every conversation against it. Tags appear as columns and filters on the conversations page, in exports, and on the Overview dashboard's Custom Tags card, complementing the intent and signals Kapa assigns on its own. Common use cases:

  • Product tags: classify by product when your company offers multiple distinct products or product areas (e.g. Container Registry, Object Storage, Managed Database).
  • Feature tags: track specific features or capabilities within a product (e.g. replication policies, automated backups, connection pooling).
  • Administrative tags: track conversations about account management, pricing, compliance, or support (e.g. Billing & Invoices, Compliance & Privacy), often to route questions to the team responsible.

Define your tags​

  1. In the Kapa platform, open the Manage Tags page.
  2. Create a tag with a name and a description that tells the AI when the tag should be applied.
  3. Repeat for each category you want to track, up to 20 custom tags per project.

A single conversation can receive multiple tags, or none if nothing matches your descriptions. Classification quality depends directly on how you write the descriptions; see the best practices below before finalizing them.

What happens after you save​

  • First-time setup: Kapa applies your tags to conversations from the last 7 days, within roughly 30 minutes, so you see results on recent conversations right away.
  • Ongoing: after you create or edit a tag, Kapa waits 10 minutes from your last change before applying anything, so you can refine descriptions without triggering intermediate runs. Tags are applied in batches roughly every 30 minutes, so expect new conversations to be labeled within about an hour.
  • After the initial backfill, new or edited tags apply to conversations going forward only.

Edit and delete safely​

  • Editing a tag applies the change to all historical assignments as well. Only edit a tag if you are not changing its meaning (e.g. fixing a typo); to change what a tag means, create a new tag and delete the old one.
  • Deleting a tag soft-deletes it: historical assignments remain visible on past conversations, and the tag is no longer applied to new ones.

Verify​

Open the conversations page and filter by one of your tags. After the backfill window, conversations from the last 7 days that match your descriptions carry the tag.

Best practices for tag descriptions​

Kapa's classification is only as good as your tag definitions: if your names and descriptions are unclear or overlapping, even humans would disagree on how to assign them. Since custom tags are assigned to whole conversations, a good starting point for any tag description is Conversations about... followed by the main topic the conversation should cover for the tag to apply.

These best practices are guidelines, not requirements. Apply the ones that are relevant to your tags. A good tag description often combines several of these techniques together.

Be specific​

The AI does not have all the same implicit context about your product that you do. Provide enough detail for accurate classification while keeping descriptions scannable. A good target is 2–3 sentences per description.

Tag name: Website Widget

Bad - too vague

Questions related to the widget.

Good - detailed and specific

Conversations about embedding the kapa Ask AI widget on websites or documentation pages using the JavaScript widget script.

Include synonyms​

Users often use different terminology than your official product names. Explicitly mentioning alternative terms ensures the tag matches even when users don't use the exact name.

Tag name: Slack Bot

Bad - uses only the official name

Conversations related to deploying kapa.ai in Slack.

Good - includes common synonyms

Conversations about deploying and configuring kapa.ai as a Slack bot, sometimes called 'Slack integration', 'Slack agent', or 'Slack assistant'.

Use concrete examples​

When a tag is hard to describe in the abstract, including specific examples of user queries can help the AI understand the intent behind the tag.

Tag name: Pricing & Billing

Bad - no examples

Conversations related to pricing and billing.

Good - includes specific user questions

Conversations about pricing and billing topics including plan selection, usage-based pricing, updating payment methods, and accessing invoices or receipts. Typical queries include 'how is usage billed?', 'How much does X cost?', 'where can I download my invoice?', 'how do I change plans?', and 'who do I contact about a billing question?'.

Include technical details​

If a tag relates to a technical feature, include specific identifiers such as URLs, API endpoints, variable names, or libraries. This enables precise matching when users paste code snippets or logs.

Tag name: HTTP API

Bad - missing identifiers

People asking about using the API to chat and search.

Good - includes specific endpoints

Conversations about calling the kapa.ai HTTP API endpoints (e.g. /query/v1/projects/:project_id/chat/, /query/v1/threads/:thread_id/chat/, /query/v1/projects/:project_id/search/). Includes API key authentication, integration_id parameters, streamed vs non-streamed chat, search queries, and questions like 'how do I pass user metadata in the API request?'.

List specific sub-topics​

List out the concrete terms, product areas, or sub-topics that fall under the tag. This helps the AI anchor the tag to specific subjects.

Tag name: Data Sources

Bad - low keyword density

Chats about configuring where kapa gets its information from.

Good - lists specific connectors and sub-topics

Conversations about configuring and troubleshooting knowledge sources such as web crawling, file uploads, GitHub, Stack Overflow, Zendesk, Jira, YouTube, Notion, and other supported connectors. Includes authentication, filters (labels, recency, paths), selector configuration, and questions like 'why is this page not indexed?', 'how often are sources refreshed?', or 'how do I add a new connector?'.

Define explicit scope boundaries​

Clarify boundaries for topics that might overlap. Explicitly state what is excluded or where the boundary lies to prevent misclassification between similar tags.

Tag name: Internal Integrations

Bad - no boundary defined

Conversations about internal integrations.

Good - defines what's included and excluded

Conversations about integrations used by internal teams, such as the internal assistant, internal Slack deployments, and MCP servers configured for internal auth.

Tag name: External Integrations

Bad - no boundary defined

Conversations about external integrations.

Good - defines what's included and excluded

Conversations about customer-facing integrations such as the website widget, the deflector, and public MCP servers.

Don't reference other tags​

Each tag description should stand on its own. Don't reference other tags by name. The AI evaluates each tag independently. If topics overlap, list the relevant keywords in both descriptions with different framing.

Tag name: React SDK

Bad - references other tags

Using the SDK. For API questions, see the 'HTTP API' tag.

Good - self-contained

Conversations about using the @kapaai/react-sdk in React applications, including KapaProvider configuration and hooks such as useChat. Typical queries include 'how do I stream answers in my React chat UI?' and 'how to pass callbacks for analytics?'.

Avoid vague catch-all tags​

Every tag should represent a clear, actionable category. Catch-all tags are not only useless on their own, they can also deteriorate the accuracy of your other well-defined tags.

Avoid, as catch-all tags swallow unrelated conversations

General: General questions.