Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chatref.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Tags

Tags are short labels that describe what a conversation is about. Chatref applies them to your chats automatically as customers talk to your bot, so you can scan the Inbox and instantly see which chats are about pricing, which are bug reports, which are refund requests — without reading every word. You write each tag once, and Chatref keeps applying it forever to every new conversation that matches.

​
How tags get applied

You don’t have to tag conversations by hand. Three things happen automatically:

On every bot reply

After your chatbot answers a customer, Chatref reads the recent conversation and applies any tags whose descriptions match.

On schedule

An hourly background job catches anything the live tagging missed and re-tags conversations whenever you change a tag’s description.

On demand

When you create or edit a tag, you can opt-in to re-tag your past conversations from the last 7 days in one click.
You never have to “run” the tagger. Just create the tag, write a clear description, and move on.

​
What tags look like

In the right pane when a conversation is open, you’ll see a row of colored chips under the Tags section: 
🔵 Pricing question   🟢 Engaged   🟠 Captured contact
Each chip:
  • Has a color you chose when you created the tag
  • Is clickable — click any chip to filter the Inbox to only conversations with that tag
  • Updates in real time as the conversation progresses
In the Inbox list, use the Filter button at the top to narrow down by tag. You can stack multiple tags (e.g. Pricing question and Engaged) for very specific queries.
The Filter button shows a small number badge when filters are active, so you always know if the list you’re looking at is filtered or complete.

​
Creating your first tag

1

Open the Tags tab

From your agent’s dashboard, click the Tags tab.
2

Click New tag

The form has three things to fill in: a name, a description, and a color.
3

Pick a clear name

Short, plain English: Pricing question, Refund request, Bug report. The name shows up as a chip.
4

Write a specific description

This is the only thing the classifier reads. Describe when this tag should apply, ideally with example phrases customers actually use. (See the next section for tips.)
5

Save

Click Create tag. From this moment forward, every new conversation will be auto-tagged based on this description — at no extra cost.
6

Optionally, re-tag your past conversations

Tick Re-tag my past conversations before saving to also apply the new tag to your last 7 days of chats. Costs 1 message per past conversation. You’ll see the exact cost before you confirm.

​
Writing good descriptions

The description is the only signal the classifier uses. Vague descriptions produce noisy tags; specific descriptions produce clean tags.

Good

“Customer is asking about pricing, plans, monthly cost, free trial, or how much the product costs. Includes phrases like ‘how much is it’, ‘what’s your pricing’, ‘do you have a free plan’, or comparing tiers.”

Too vague

“Pricing stuff”The classifier guesses what you mean and applies the tag too broadly.
Tips:
  • List the trigger phrases customers actually use. Quote them directly.
  • State the boundary. “Only when discussing money/cost, not when asking about features.”
  • Keep it under 500 characters. That’s the field limit.
  • Avoid jargon the model wouldn’t know. Use the customer’s words.

​
Suggested tags to start with

The most useful tags depend on your product, but these are a good starting set most teams find valuable. Each one is shown with a name, a description you can paste, and the inbox use case.
DescriptionCustomer is asking about pricing, plans, monthly cost, free trial, or how much the product costs. Includes phrases like “how much is it”, “what’s your pricing”, “do you have a free plan”, or comparing tiers.Use caseFilter to this tag to see purchase-intent conversations. Pair with Captured contact to find leads who left contact info while shopping.
DescriptionCustomer wants a refund, return, or money back. Includes “I want my money back”, “refund please”, “cancel and refund”, or disputing a charge.Use caseSpot refund requests immediately so you can respond before they escalate. Often pairs with Wants human.
DescriptionCustomer reports a technical issue, error message, broken feature, or unexpected behavior. Includes “it’s not working”, “I’m getting an error”, “the button doesn’t do anything”, “this page is broken”.Use caseDaily review by product/engineering. Filter by this tag to triage real defects from confusion.
DescriptionCustomer suggests a new feature, improvement, or capability the product doesn’t currently have. Includes “it would be nice if”, “can you add”, “I wish you had”, “any plans to support X”.Use caseRoll up into your product backlog. Pair with Captured contact to follow up with the requester when shipped.
DescriptionCustomer typed at least one real message (not just clicking suggestion bubbles) and seems genuinely interested in the answer. Excludes single-click visitors who left immediately.Use caseThe “meaningful chats only” filter. Tick Engaged in the Filter dropdown to hide one-click bouncers and focus on conversations where the customer actually engaged.
DescriptionThe customer shared an email address or phone number anywhere in the conversation. Useful for identifying leads or follow-up opportunities.Use caseLead pipeline. Combine with a topic tag like Pricing question to find sales-ready leads.
DescriptionThe customer asked to talk to a real person, a human agent, support, or expressed frustration that the bot couldn’t help. Includes “can I talk to a human”, “this isn’t working”, “is anyone there”, or requests to escalate.Use caseReal-time escalation queue. Pair with Human Handoff so a teammate can take over.
DescriptionCustomer is new to the product and asking how to get started, set up their account, configure their first agent, or understand basic concepts. Includes “how do I begin”, “what’s the first step”, or confusion about the initial setup flow.Use caseSpot friction in your onboarding. If this tag spikes, your getting-started experience needs work.
You don’t need all of these on day one. Start with two or three tags that match your most common conversation types, and add more as you see patterns in the Inbox.

​
Re-tagging your past conversations

When you save a new tag or change an existing one’s description, Chatref applies it to new conversations going forward, for free. Your past conversations are not touched unless you opt in. To apply a tag to past conversations:
1

Tick the checkbox

On the tag form, tick Re-tag my past conversations.
2

Review the cost

You’ll see exactly how many past conversations are eligible (up to 200 from the last 7 days) and how many messages it will cost. Costs 1 message per past conversation.
3

Confirm or cancel

If you have enough messages in your balance, click Save and re-tag to confirm. If not, you’ll see an Upgrade button to top up your account.
4

Wait up to an hour

Re-tagging runs in the background on an hourly schedule. Your past conversations will be re-tagged within the next hour — no need to keep the page open.
The 7-day window and 200-conversation cap are deliberate cost controls. Conversations older than 7 days are kept in your database and can be searched, but won’t be re-tagged automatically.

​
Limits

LimitValueWhy
Active tags per agent5Each tag is part of the prompt sent to the classifier. Keeping the list short keeps the classifier accurate AND keeps your message cost predictable.
Description length500 charactersLong descriptions make the classifier slower and don’t usually improve accuracy.
Re-tag past conversations windowLast 7 daysOlder conversations rarely need re-tagging — they’re already settled.
Re-tag past conversations cap200 per tag, per runHard ceiling on a single re-tag operation.
If you hit the 5-tag limit, disable or delete an existing tag before creating a new one. Disabled tags stop applying to new conversations but stay in the database, so you can re-enable them later.

​
How does the classifier work?

You don’t need to read this section to use tags, but it helps to know what’s happening behind the scenes. Each time your chatbot replies to a customer, Chatref:
  1. Pulls the last 20 messages of that conversation
  2. Sends them to the AI tagging model alongside your active tag list (with their descriptions)
  3. Gets back a list of tags that apply, with a confidence score
  4. Saves any tag with confidence above 60% to the conversation
Tagging runs on a lightweight model optimized for short, structured classification tasks. That’s a deliberate choice — a simpler job needs a simpler, lower-cost model, which keeps tagging fast and keeps your costs down. Cost: 1 message per classification call. On a typical conversation where the customer sends 5 messages, you’ll spend roughly 5 messages on tagging across the conversation’s lifetime — bundled into the cost you’re already paying for the chat replies themselves.
You’re never charged extra for tagging on top of a chat reply. The “1 message” cost only applies when you explicitly re-tag a conversation (clicking the re-tag button or ticking the past-conversations checkbox).

​
Frequently asked questions

The classifier needs at least 2 messages in a conversation before it runs. Brand-new chats with just a bot greeting won’t have tags yet. Once the customer replies, tags should appear within a couple of minutes.If a conversation has plenty of messages but no tags, it usually means the classifier read the conversation but none of your tags matched with high enough confidence. That’s not a bug — it’s the classifier being honest that nothing applies.
Not yet. The classifier owns auto-applied tags so they stay consistent with your tag’s description. If a tag is being applied where it shouldn’t, edit the description to be more specific (e.g. add “Only when the customer is asking about money, not when asking about features”) and tick the Re-tag past conversations checkbox on save to refresh the existing rows.
99% of the time, it’s the description. If a tag is over-applied, your description is too broad. If it’s under-applied, your description is too narrow or doesn’t include the phrases customers actually use.Open the tag, look at 5 conversations that got it wrong, and rewrite the description to include the right examples and exclude the wrong ones.
Every tag’s description is included in the system prompt the classifier reads on every call. Bigger prompt → higher cost per call, and (counterintuitively) lower accuracy because the model has to choose between more similar-sounding options.Five well-chosen, distinct tags give you clean signal. Twenty overlapping tags give you a mess.
Automatic tagging on new conversations continues for free — it’s bundled into the chat reply you’re already paying for.What stops working is re-tagging past conversations: the opt-in checkbox on the tag form and the “Re-tag past conversations” button on the Tags list. These both need messages to charge. You’ll see a clear Upgrade button if you try one with an empty balance.
Yes. Click the Filter button at the top of the Inbox, expand the Tags section, and tick the tag(s) you want. The Inbox list filters live. You can stack multiple tags to narrow down further.You can also click any tag chip on an open conversation (in the right pane) to filter to that tag instantly.
Tags replace buckets. Buckets were a fixed 3-state system (Needs attention, Resolved by AI, Unassisted) that worked for everyone but couldn’t capture what your business cared about. Tags let you create the exact categories you need — pricing questions, refund requests, leads, whatever matters — and filter on combinations of them.If you used the buckets before, the closest equivalent today is to create an Engaged tag (using the description in the Suggested tags section above) and filter by it.