Tutorial: Add complex topics

Some FAQs 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.

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 FAQs 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

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 complex 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

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?

Check your understanding