Conversation Orchestration

Status: Implemented Owner: @bilal Last Updated: 2026-02-15

How the AI manages tenant conversations and routes between Q&A, issue creation, and escalation.

The Problem

A single tenant conversation may involve multiple intents:

Example	Looks Like	Actually Is
”Is there a BBQ area?”	Q&A	Info only
”The BBQ area is broken”	Issue	Maintenance request
”My heating isn’t working”	Issue	Could be FAQ (how to use thermostat) or real issue

Intent Classification

Intent	Next Action
question	RAG retrieval + answer
issue_report	Issue intake flow
issue_followup	Issue lookup
greeting	Persona greeting
thanks	Polite close
unclear	Clarifying question
out_of_scope	Polite redirect

Classification uses LLM with confidence threshold (>= 0.85 = use directly, < 0.85 = check context).

Conversation State Machine

stateDiagram-v2
    [*] --> greeting
    greeting --> qa_mode : Question
    greeting --> issue_intake : Issue
    qa_mode --> issue_intake : Problem emerges
    qa_mode --> closing : Thanks
    qa_mode --> escalation : Cannot answer
    issue_intake --> issue_created : All details collected
    issue_intake --> qa_mode : Actually a question
    issue_intake --> escalation : Emergency
    issue_created --> closing : Confirmed
    escalation --> [*] : Handed to human
    closing --> [*]

Handoff: Q&A to Issue

When conversation shifts from Q&A to issue reporting, context is preserved:

• Inferred category from prior Q&A
• Attempted solutions (what tenant already tried)
• Related documents found during Q&A
• Full conversation history

Escalation Triggers

Trigger	Action
Emergency keywords	Immediate escalation + emergency contact numbers
3+ “I don’t know” responses	Offer human handoff
Explicit request (“speak to a person”)	Transfer
Sensitive topics	Human required

Edge Cases

FAQ disguised as issue: “My heating isn’t working” — check for simple fix in docs first, offer instructions, then escalate to issue if still broken.

Mid-conversation topic switch: Pause current state, answer new question, return with prompt.

Abandoned intake: 5 min reminder → 15 min save partial → 24h clear state.

Multiple issues: Handle one at a time, create separate issues.

Channel-Specific Behaviour

Aspect	Chat	Voice	WhatsApp
Response length	200 words	75 words	150 words
Formatting	Markdown	Plain speech	Basic (bold, lists)
Follow-ups	Multiple OK	Max 2	Async OK
Session	30 min timeout	Single call	24h context

See also: RAG Pipeline, Issue Lifecycle