Conversation Flow

Overview

Every conversation follows a linear series of steps defined by the active industry template. The AI agent advances through each step only after the required information has been collected — it never skips ahead or loops back.

Step-by-step flow

The general flow across all templates follows this pattern:

Customer sends message
        ↓
    Greeting
        ↓
  Service Selection
        ↓
  Contact Collection
        ↓
  Check Availability
        ↓
  Present Time Slots
        ↓
  Confirm Booking
        ↓
    Book Appointment
        ↓
      Done

Industry-specific templates add extra steps between these core ones. For example, the Trades template adds urgency triage, address collection, and photo requests between service selection and contact collection.

How step advancement works

Steps advance deterministically based on tool calls, not based on what the AI writes in text. This is a key design decision that prevents the agent from skipping steps or advancing prematurely.

For example:

• The agent only advances past "Contact Collection" when update_lead_status is called with a name and email
• The agent only advances past "Slot Presentation" when the customer selects a specific time
• The agent only creates a booking when create_booking is called after explicit customer confirmation

The advance_step logic runs after every tool call and checks what data has been collected to decide whether to move forward.

Conversation state

Each conversation maintains state that persists across messages:

Collected data fields

How the agent handles edge cases

Missing information

If a customer provides incomplete information (e.g. gives their name but not email), the agent stays on the current step and asks for the missing piece. It does not advance until all required data for that step is collected.

Off-topic questions

The agent can handle brief off-topic questions (e.g. "What are your opening hours?" or "Where are you located?") by answering from the business context, then steering back to the current step.

Repeated misunderstanding

If the agent cannot understand the customer after multiple attempts, or the customer explicitly asks for a human, the agent calls the escalate_to_human tool.

Escalation

When the agent escalates a conversation:

1. The escalate_to_human tool is called with a reason
2. The conversation status is set to escalated in the database
3. A notification email is sent to the business owner
4. The agent tells the customer that a team member will follow up
5. The conversation appears with an "Escalated" badge in the dashboard

Escalation triggers include:

• Customer explicitly asks to speak to a person
• The customer's request is outside the agent's capabilities
• The customer is frustrated or unhappy
• Complex scenarios the agent isn't designed to handle