AI Topics automatically groups your conversations into themes so you can see what customers contact you about most, and turn recurring patterns into guidance for your AI agents.
Topics are discovered for you. You do not create them manually. When you first turn AI Topics on, Heymarket reviews your recent conversation history to build the initial set of topics. After that, a daily job folds newly closed conversations into existing topics, and a weekly recluster reorganizes the full set so topics stay accurate as your volume changes.
Where to find it: Admin > AI > AI Topics: https://app.heymarket.com/admin/hey-ai/ai-topics/
Turning AI Topics on
Use the toggle at the top right of the AI Topics page to enable or disable topic discovery for your account. The first time you enable it, Heymarket runs a one-time pass over your recent conversations to build your starting topics — this can take a while. After that, the daily and weekly jobs run automatically.
At the top of the page you will see four summary metrics:
| Metric | What it means |
|---|---|
| Topics | Total number of auto-discovered topics |
| Conversations classified | Conversations assigned to a topic across all topics |
| Unclustered | Conversations not yet assigned, waiting for the next recluster |
| Last backfill | When conversation history was last processed |
Use the date range picker at the right of the tab bar to scope what you are looking at.
The Topics tab
The Topics tab lists every discovered topic with its description, conversation count, and the date it was last seen. Click the Conversations column header to sort by volume.
Some topics have a triangle to the left of the title. Expand it to see subtopics, which are narrower themes grouped under a broader parent. For example, SMS Delivery Failures may contain a more specific Message Delivery Failures subtopic.
Opening a topic
Click a topic title to open its detail panel. The panel shows the topic description, conversation count, and last seen date, plus two tabs: Conversations and Playbook.
The Conversations tab lists every conversation assigned to the topic. Click any conversation to open it.
Editing, merging, and deleting a topic
Three actions sit at the top of the detail panel:
- Edit updates the topic title and description.
- Merge moves all conversations from this topic into another topic, then deletes the source topic. Use this when the clustering job has split one real theme across two topics.
- A topic that has subtopics can't be merged — handle the subtopics first. If both topics have a playbook, the destination topic's playbook is kept
- Delete removes the topic, along with any subtopics under it and their playbooks. The conversations return to Unclustered.
When you click Merge, choose the target topic from the dropdown. Conversation counts appear next to each option so you can pick the larger, better established topic as the destination.
Playbooks
A playbook is written guidance attached to a topic. When a live conversation matches that topic with at least 90% confidence, the playbook is injected into your AI agent's context as authoritative team guidance, alongside knowledge base results.
Use playbooks for process, not facts. Knowledge base articles answer what is true. Playbooks tell the agent what to do: what to verify first, what to ask for, when to hand off to a human.
Writing a playbook from scratch
Open a topic, go to the Playbook tab, and write your guidance in the text field. You have up to 8,192 characters. Click Create playbook, then use the Enabled toggle to make it live.
Letting AI draft it for you
Click Suggest from past resolutions and Heymarket reads how your team actually resolved conversations in this topic, then drafts a playbook from them. If the topic doesn't have enough resolved conversations yet, Heymarket can't draft from it — keep the topic and try again once your team has closed a few more. Once you edit a draft yourself, it becomes yours and AI won't overwrite it; use Refresh draft if you want a new version.
Drafts are never enabled automatically. The tab label reads Playbook (off) until you approve it, and a banner tells you how many past resolutions the draft came from. The Drafted from section at the bottom lists those conversation IDs so you can check the source material.
Review and edit the draft, then choose:
- Approve & enable makes the playbook live for your agents.
- Refresh draft regenerates it from the latest resolutions.
- Delete discards the draft.
Always read a draft before enabling it. It reflects what your team did historically, including any outdated steps.
Reports
The Reports tab shows how your conversation volume is distributed across topics.
- Topic distribution breaks out your highest volume topics by count and percentage, with everything else grouped into Other and Unclustered.
- Trends plots your top five topics over time so you can spot spikes.
Switch between Daily and Weekly granularity, and use the date range picker to change the window.
Runs
The Runs tab is a log of every clustering job, useful when topic counts look wrong or stale.
| Kind | Trigger | What it does |
|---|---|---|
| Incremental | Daily job | Folds newly closed conversations into existing topics |
| Recluster | Weekly recluster | Reorganizes all conversations, creating and updating topics |
| Backfill | Manual | Processes historical conversations in bulk |
Each row shows status, conversations processed, and how many topics were created or updated. An incremental run showing 0 / 0 simply means no conversations closed that day.
FAQ
Why are conversations sitting in Unclustered? Unclustered conversations are waiting for the next weekly recluster. They are picked up automatically.
Can I create a topic myself? No. Topics are discovered automatically. You can edit titles and descriptions, merge topics, and delete them.
Do playbooks replace the knowledge base? No. Playbooks supply process guidance and are delivered alongside knowledge base results, not instead of them.
Do playbooks apply to human agents too? The playbook field is written as guidance for handling the topic, and it is injected into AI agent context when a conversation matches. Human agents can read it in the topic panel.
Why did my topic disappear? It was likely merged into another topic during a recluster, or a teammate merged or deleted it manually. Check the Runs tab for recent recluster activity.
What happens if I turn AI Topics off? Discovery jobs stop running, and any setup pass in progress is cancelled. Existing topics and playbooks are kept. Turning it back on later resumes discovery without rebuilding your topics from scratch.
Why isn't a specific conversation in any topic? Very short conversations don't have enough back-and-forth to place, and unusually long ones tend to cover several issues at once. Both are left out to keep topics accurate. Everything else waits for the next weekly recluster.