How to write good custom tags
Custom tags let you classify conversations into categories specific to your business. Each tag has a name and a description that tells the AI when it should be applied. 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. This guide helps you define your custom tags to maximize classification accuracy.
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
Questions related to the widget.
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
Conversations related to deploying kapa.ai in Slack.
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
Conversations related to pricing and billing.
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
People asking about using the API to chat and search.
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
Chats about configuring where kapa gets its information from.
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
Conversations about internal integrations.
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
Conversations about external integrations.
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
Using the SDK. For API questions, see the 'HTTP API' tag.
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.
General: General questions.