Add complex Knowledge Base topics

Not all Knowledge Base topics are simple question-and-answer entries. Some need to guide the user through a decision, send information by text, or route the conversation to the right place when the request isn’t clear.

This lesson explains what makes a topic “complex”, and shows a set of reliable patterns you can reuse. The goal is not cleverness, but predictability: topics that retrieve correctly, behave well in Chat and Call, and recover cleanly when users respond in unexpected ways.

What makes a Knowledge Base topic complex?

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

In practice, that usually means at least one of the following:

• The agent triggers an action, such as sending an SMS, transferring a call, or routing to somewhere else in the project.
• The agent presents options and waits for the user to choose before proceeding.
• The agent must ask a clarifying question before it can act.

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

Before you write anything

Complex topics work best when you make some decisions and plan.

Be clear on these points first:

• What is the intended outcome of this topic? For example: the user receives a link by SMS, or is transferred to the front desk.
• What should happen if the user says no?
• What should happen if the user gives an answer you didn’t expect?

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.

Topic naming matters more than you think

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 request is interpreted internally.
• It reduces collisions with any other billing topics you may add as your knowledge base grows.

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.

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

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

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

Why this often takes longer than expected

Teams usually struggle because they:

1. Overload a single topic with multiple intents
2. Write perfect answers but weak retrieval
3. Delay Call testing until late

The fix is simple and consistent:

• Lock retrieval first
• Keep topics single-purpose
• Test messy, real-world phrasing early

Resources

• Knowledge Base best practices (RAG and retrieval)
• FAQ troubleshooting
• Knowledge Base maintenance and governance

Progress
4 of 11 lessons complete