Add complex topics

Build Managed Topics with actions, disambiguation, and multi-turn patterns.

Level 2 — Lesson 1 of 8 — Build multi-turn flows with SMS, handoffs, and conditional logic.

Reading the action notation in this lesson: This lesson references functions like start_sms_flow and transfer_call. You’ll learn how to create and wire these in Lesson 2: Using functions and Lesson 3: Return values.

For now, read them as named actions:

• start_sms_flow with sms_id="bill_request" → sends an SMS using the template called “bill_request”
• transfer_call with transfer_reason="BILLING" → transfers the caller to a human agent for billing

Focus on the topic patterns and when each applies. The implementation details come next.

Some Managed Topics need to guide a decision, send a text, or route the conversation. This lesson covers reliable patterns for topics that retrieve correctly, behave in Chat and Call, and recover from unexpected responses.

What makes a Managed Topic complex?

A topic is considered complex if it does more than return static information.

Actions

Triggers SMS, transfers, or routing

Options

Presents choices and waits for user selection

Clarification

Asks questions before acting

In the UI, complex topics almost always use both Content and Actions, and often rely on functions to control what happens next.

Topic creation flow

Before you write anything

Answer these first:

• What is the intended outcome? (e.g., user receives SMS link, or gets transferred)
• What happens if the user says no?
• What happens if the user gives an unexpected answer?

An example workflow for complex topics

Step 1: Retrieval

If a topic doesn’t retrieve reliably, nothing else matters. Retrieval depends most on three things, in this order:

1. Topic name
2. Sample questions
3. Content

Most early failures are derived from retrieval.

Why topic naming is critical

The topic name is one of the strongest signals used to decide which content to surface. A good name should represent one specific user intent, for example:

bill_request_previous_stay

Why this works:

• It represents a single, concrete intent.
• It distinguishes between similar scenarios (previous stay vs current or future).
• It mirrors how the system classifies the request.
• It reduces collisions with any other billing topics you may add as your Managed Topics grow.

Here are some bad examples:

• billing
• help_with_bill
• misc_billing

These fail because they are too broad. They force the system to guess, increase the chance of the wrong topic being selected, and become harder to maintain as you add more billing flows.

Step 2: Write sample questions like real users

Think of sample questions as training data.

For complex topics, aim for variety. Include:

• Direct commands
• Polite requests
• Incomplete phrasing
• Synonyms and alternate terminology
• Call-style filler language

For example, for a billing topic:

• Can you send me my invoice
• I stayed last week and need a receipt
• Text me my bill
• I need a folio from my last stay
• Uh I need billing help

Step 3: Write Content like a call script

Content should sound natural when spoken out loud.

As a rule, it should:

• Lead with what happens next
• Ask one clear question
• Be short enough to say in a single breath

Avoid explanations unless they are strictly necessary for the decision the user is being asked to make.

Check your understanding

Core complex patterns (with examples)

The patterns below cover most real-world use cases. You can copy them directly and adapt the wording.

Pattern 1: Offer SMS with fallback to handoff

Use when

• The user needs a link, form, or written instructions.

Topic name bill_request_previous_stay

Content

The easiest way to get a bill from a previous stay is online.
I can send you a text with the link if you'd like.
Would you like me to send that now, or would you rather speak to someone?

Actions

- If user agrees → `start_sms_flow` with `sms_id="bill_request"`
- If user declines → offer or trigger handoff to billing
- If SMS fails → transfer automatically

Why this works

• Consent is explicit
• Only two options are presented
• There is a clear fallback

Pattern 2: Conditional SMS (user chooses)

Use when

• Multiple follow-ups are possible.

Topic name promotions_current

Content

I can send you details about this week's promotion.

Would you like information about today's offer,
upcoming events, or loyalty rewards?

Actions

- If "today" → `start_sms_flow` with `sms_id="promo_today"`
- If "events" → `start_sms_flow` with `sms_id="promo_events"`
- If "rewards" → `start_sms_flow` with `sms_id="promo_rewards"`

Handle loose answers such as “the first one” or “events please”.

Pattern 3: Direct handoff (no agent reply)

Use when

• The agent should not attempt to resolve the request.

Topic name out_of_scope_spanish

Content (leave empty)

Actions

• Immediately call transfer_call with transfer_reason="SPANISH"

This avoids unnecessary turns and makes ownership explicit.

Pattern 4: Answer, then offer handoff

Use when

• The agent can answer, but escalation may still be useful.

Topic name late_checkout

Content

Standard checkout is at 11 a.m.

If you need to check out later than that, I can connect you with the front desk to see what’s available. Would you like me to do that?

Actions

• If yes → handoff to front desk
• If no → end politely

Pattern 5: Clarify, then route

Use when

• The intent is genuinely ambiguous.

Topic name reservation_change

Content

Are you looking to change an existing reservation, or make a new one?

Actions

• If “change” → route to reservation modification
• If “new” → route to booking flow

Rules:

• Ask one question only
• Do not stack clarifications
• Complete the flow immediately after the answer

Pattern 6: Info + action hybrid

Use when

• The user needs context and a next step.

Topic name lifeline_program

Content

Lifeline is a government-sponsored program that provides qualifying customers with discounted phone or broadband service.

I can text you more details, or connect you with a specialist. Which would you prefer?

Actions

• SMS → start_sms_flow
• Handoff → transfer_call

Pattern 7: Info-only (still complex in practice)

Use when

• The information is static but sensitive or high-impact.

Topic name housekeeping_hours

Content

Housekeeping is available daily from 9 a.m. to 5 p.m.

If you need service outside those hours, I can connect you with the front desk.

Actions

• No automatic action
• Offer handoff only if asked

Creating a complex topic in the UI

1. Go to Build → Knowledge

   Click + Add topic to create a new Managed Topic.

2. Set the topic name

   Use a specific, single-intent name (e.g., bill_request_previous_stay).

3. Add sample questions

   Write 10+ variations of how a real user would phrase this request.

4. Write Content

   In the Content field, write the agent’s response in call-script style — short, spoken-friendly, ending with one clear question.

5. Add Actions

   Below Content, click Add action. Configure each branch:

   • Select the function to call (e.g., start_sms_flow, transfer_call)
   • Set the condition (e.g., “If user agrees”, “If user declines”)
   • Add fallback actions for error cases
6. Test retrieval

   Open Chat and ask several phrasings. Confirm the correct topic triggers before testing in Call.

Writing content that works in Call

Do

• Use short sentences
• End with a single question
• Make one decision per turn

Don’t

• Use paragraphs
• Include internal notes
• Ask multiple questions at once

Action design rules

• One primary outcome per turn
• Explicit consent before SMS
• A safe fallback for silence or confusion
• Prefer clarity over clever branching

Check your understanding

Verification checklist

Retrieval

• Topic triggers with at least 10 phrasing variations

Chat

• Consent is respected
• No looping

Call

• Responses are listenable
• Users can interrupt naturally
• No dead ends

Failure cases

• Unexpected answers recover cleanly
• SMS failures route correctly

Common pitfalls

1. Overloading a topic with multiple intents
2. Writing perfect answers but weak retrieval
3. Delaying Call testing

Fix: ensure retrieval works reliably first, keep topics single-purpose, and test varied phrasing early.

Try it yourself

1. Challenge: Write a 'bill request' complex topic

   Write a complete complex topic for a hotel guest requesting a bill from a previous stay. Use Pattern 1 (SMS with fallback to handoff).

   Include:

   1. Topic name
   2. Four sample questions
   3. Content (2–3 sentences, call-script style)
   4. Actions (3 branches: agree to SMS, decline SMS, SMS fails)

   Hint

   The topic name should describe one specific scenario (not just “billing”). Content should lead with what happens next and end with one clear question. Actions should cover the “yes”, “no”, and “error” paths.

   Example solution

   Topic name: bill_request_previous_stay

   Sample questions:

   • can you send me my bill from last week
   • I need a receipt from my last stay
   • text me my invoice
   • how do I get a folio for my previous visit

   Content:

   The easiest way to get your bill is online.
   I can send you a text with the link — would you like me to do that,
   or would you prefer to speak with someone at the front desk?
   

   Actions:

   • If user agrees → start_sms_flow with sms_id="bill_request"
   • If user declines → transfer to front desk
   • If SMS fails → transfer automatically

Check your understanding

← Back to PolyAcademy

Level overview

Next: Using functions →

Lesson 2 of 8