;
};
**Level 2 – Lesson 1 of 8** – Build multi-turn flows with [SMS](/managed-topics/how-to-setup-action/send-sms), [handoffs](/managed-topics/how-to-setup-action/handoff), 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 tools](/learn/guides/advanced/using-tools) and [Lesson 3: Return values](/learn/guides/advanced/tool-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](/managed-topics/introduction) 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.
Triggers SMS, transfers, or routing
Presents choices and waits for user selection
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
```mermaid theme={null}
flowchart TD
A[New complex topic idea] --> B[Define intended outcome]
B --> C[Choose topic name – one specific intent]
C --> D[Write sample questions – 10+ variations]
D --> E[Write Content – call script style]
E --> F[Add Actions – SMS / handoff / routing]
F --> G{Test retrieval in Chat?}
G -->|Fails to trigger| C
G -->|Triggers correctly| H{Test in Call?}
H -->|Responses too long or unnatural| E
H -->|Passes| I{Test failure cases?}
I -->|Dead ends or loops| F
I -->|Recovers cleanly| J[Ready to promote]
```
## 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**
```text theme={null}
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**
```text theme={null}
- 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**
```text theme={null}
I can send you details about this week's promotion.
Would you like information about today's offer,
upcoming events, or loyalty rewards?
```
**Actions**
```text theme={null}
- 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
Click **+ Add topic** to create a new Managed Topic.
Use a specific, single-intent name (e.g., `bill_request_previous_stay`).
Write 10+ variations of how a real user would phrase this request.
In the **Content** field, write the agent's response in call-script style – short, spoken-friendly, ending with one clear question.
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
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
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)
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.
**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:**
```text theme={null}
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
Level overview
Lesson 2 of 8