Managed topics

Use Managed Topics to give your agent answers to the questions callers ask most often — return policies, store hours, appointment availability, account lookups. Each topic contains sample questions, an answer, and optional actions. Keeping topics up to date helps your agent resolve more calls without escalation.

Managed Topics are found under Build > Knowledge > Managed Topics tab.

Use Managed Topics when you need precise control over what the agent says, or when the answer should trigger an action (SMS, handoff, function call). Use Connected Knowledge instead when you want to expose large volumes of external content (help articles, PDFs, FAQs) without curating individual topics.

If you need to add custom logic to your topics — such as API calls, data lookups, or conditional behavior — see the Tools section under Build in the sidebar.

The Managed Topics interface

Search, filter, and manage topics. Click any topic card to edit.

How retrieval works

The agent does not see all MTs at once. Instead, it uses retrieval-augmented generation (RAG) to find the best match for the user’s message.

1. The retriever compares the message to the topic’s name, sample questions, and content — with higher weighting given to the name and sample questions.
2. It returns the top matching topics to the LLM.
3. The LLM selects the best match and generates a reply (and may trigger an action).

For best topic matching and response quality, use PolyAI’s Raven model. Raven is trained to ground its answers in retrieved topics — it will say “I don’t know” rather than hallucinate when information isn’t available, and it converts topic content into natural conversational responses without needing example utterances.

Types of Managed Topic entries

Simple FAQ

Used when the agent just needs to answer a question with no follow-up or action required.

Single turn

One message in, one message out.

• Add a short, helpful reply in content.
• Leave actions empty.

Multi turn

Ask a clarifying question before giving the answer.

• Use branching inside content to structure the reply.
• Leave actions empty.

Example – Pet policy (multi-turn)

Handoff

Used when the agent should offer to connect the user to a human agent.

Offer

Agent replies, then offers to transfer.

• content: Include the answer and the offer.
• actions: Trigger transfer_call (or another handoff function) only if the user accepts.

Example – Spa booking

Direct

Immediate transfer with no agent reply.

• Leave content empty.
• Always run transfer_call in actions.

Example – Billing handoff

Conditional

Transfer based on user clarification — for example, group size or request type.

• content: Ask a disambiguating question.
• actions: Map each answer to the correct destination.

Example – Room reservations

Outbound messaging

Used when you want to send a follow-up message via SMS or WhatsApp.

Offer

Offer to send a link via message.

• content: Include a short message and ask for consent.
• actions: If accepted, call start_sms_flow. See SMS setup for details.

Example – Send a link

Conditional

Let the user choose which message to receive.

• content: Ask a branching question.
• actions: Map answers to different sms_ids.

Example – Conditional SMS

Info only

Used for static reference material (like opening hours or prices). No interaction or action required.

• Fill content.
• Leave actions empty.

Example – Opening hours

Best practices

Writing good sample questions

Include at least 3 sample questions per topic. This baseline helps the AI generalize intent across typical phrasings. For broad topics, add more to ensure better coverage.

• Focus on variety in language and structure
• Think about how real users might describe the same issue — confused, specific, vague, or using non-standard terminology
• Additional examples should reflect distinct phrasings, not slight rewordings
• Vary sentence lengths alongside phrasing variety

If migrating from an intent-based project, you might have more than 10 sample questions. Focus on keeping the most diverse items that preserve the full semantic scope of the original list.

Topic naming

Because the topic Name is shown to the retriever, it should be semantically close to the topic content. For instance, a topic about payment disputes named “general_behavior-payment” will likely trigger on payment queries in general rather than only on disputes. Make topic names semantically descriptive.

General guidelines

Do this:

• Use specific topic names.
• Add up to 20 realistic sample phrasings per topic.
• Keep replies short, helpful, and on-brand.
• Use actions only when necessary.
• Split multi-part flows into separate turns or topics.
• After simple FAQs, ensure the agent asks if the user needs more help — either in the topic content or via a global rule.

Avoid this:

• Bundling multiple intents into one topic.
• Running too many actions in a single turn (keep it simple — one or two is usually enough).
• Using vague topic names like Misc, Help, or Info.

Common anti-patterns

Mixing text and function calls in one turn: For best results, split utterances and function calls into separate turns — give the agent one task per turn.

Good

Turn 1: Agent answers the question and asks if the user wants to be transferred.

Turn 2: If the user says yes, call transfer_call with a handoff utterance.

Bad

Single turn: Answer the question, then immediately call transfer_call with utterance — the agent may skip one of these tasks.

Live collaboration

Multiple users can edit Managed Topics at the same time. Changes are synced in real time, so you can collaborate on topic content without overwriting each other’s work.

Activating and deactivating topics

Not every topic needs to be available all the time. You can temporarily deactivate a topic to keep it out of retrieval without deleting it or removing its content.

• Inactive topics are ignored by the LLM and marked clearly in the UI.
• Activation status is environment-specific, so you can test changes safely in Sandbox before going live. Learn more about environments and versions.
• CSV import/export includes an Active column (Y/N) for bulk updates.

This is useful for seasonal articles, phased rollouts, A/B tests, or hiding content that is not ready for production.

Resources

Actions guide

Add function calls, handoffs, and SMS triggers to topics.

FAQ troubleshooting

Common issues with topics, rules, and actions.

Maintenance guide

Keep topics accurate and up to date over time.