Skip to main content

Chatbot Flow Builder

Audience: Sales · Management · QA · Support · Engineering · Where in app: Settings → AI Agents → Chatbot Flows · Plan availability: All plans; number of flows per company is plan-dependent (verify)

The Chatbot Flow Builder is a visual, drag-and-drop tool for designing structured, rules-based conversation flows — the deterministic alternative to a free-form AI chatbot. You lay out the steps a visitor takes (questions, choices, forms, bookings), connect them, and the widget walks visitors through exactly that path. Ideal when you need precise control: lead qualification, department routing, compliance/regulated intake, or a fixed booking funnel.

What it does​

  • Runs a fixed decision tree instead of (or before) the free-form AI Chat Agent.
  • Collects structured information (name, email, phone, custom fields) through guided steps.
  • Branches based on the visitor's choices.
  • Tags visitors (feeding lead scoring), opens a calendar picker, or hands off to a human.
  • Can hand off to the AI Chat Agent at any node once qualification is done.

How it works​

Where it lives. companies.chatbot_enabled = true and companies.chatbot_type = "flow". The flow definition is stored in ChatBotModel:

{
  company_id,
  name,
  flow: Mixed,            // the decision tree
  auto_trigger: bool,
  disable_ai_suggestions: bool
}

Real-time engine. The flow engine runs in ms-communication, not ms-ai. As the visitor responds, the socket event ai-next-node advances the flow to the next node. ms-ai's POST /ask-flow endpoint handles flow-based chat routing where the AI is involved.

Mixing flow + AI. Set handoff_to_ai: true on a node to hand the conversation to the Chat Agent after that point — e.g. run a scripted qualification, then let the AI take over the open-ended Q&A. The AI then grounds answers in the Knowledge Base as usual.

Configuration & options​

Creating a flow: Settings → AI Agents → Chatbot Flows → Create New Flow → name it → the visual editor opens with a Start node already placed. Drag nodes onto the canvas, configure each via its side panel, and connect them.

Node types:

NodeWhat it does
StartEntry point. Exactly one per flow (auto-placed).
MessageSends a text message to the visitor (greeting, info, setup).
Input / QuestionAsks the visitor to type a response — free text, choice, email, or phone.
Choice / BranchPresents options → different paths.
FormMulti-field capture in one step.
TagAssigns a tag to the visitor (used in lead scoring).
BookingOpens a calendar picker (Google / Calendly / GHL).
HandoffTransfers to a human agent.
EndEnds the flow.

Key options:

OptionEffect
auto_triggerIf true, the flow runs as soon as the chat opens (the first node is the greeting — no separate greeting message). If false, it waits for the visitor to message first.
disable_ai_suggestionsIf true, the visitor can't type free-form during the flow — only choose from buttons. Use for strictly guided flows.
handoff_to_ai (per node)Hands off to the AI Chat Agent from that node.

Page-specific flows. Different flows can be assigned to different URLs via page rules + flow ID (e.g. a contact-form flow on /contact, a booking flow on /demo).

QA tip: start with a simple 3–5 node flow and expand — complex flows are harder to test and maintain.

Behaviors & edge cases​

  • Free-form lockdown. With disable_ai_suggestions: true the visitor is restricted to buttons; useful for compliance but frustrating if a path is missing — always provide an escape (a Handoff or a catch-all branch).
  • No greeting on auto-trigger. When auto_trigger: true there's no separate greeting message; the first flow node is the greeting.
  • Handoff to human. A Handoff node transfers to a human agent (same takeover path as the Chat Agent).
  • Flow vs. AI cost. Pure flow steps (messages, choices, forms) are deterministic and don't call an LLM, so they don't consume AI Credits. Credits are only used once a node hands off to the AI Chat Agent. See AI Credits.
  • Sensitive data. Flows that capture sensitive data should match the tenant's verification policy.

Plan & limits​

  • Available on all plans.
  • Number of flows per company is plan-dependent (verify).
  • Flow depth (max chained nodes) is bounded for performance (verify the cap).

What Nox can tell you​

  • Whether the flow chatbot is enabled and how many flows exist.
  • How often each flow completes (via session analyses + chat outcomes).

Nox can't edit flows.

Technical implementation​

  • Definition store: ChatBotModel (backend Mongo). Flags: companies.chatbot_enabled, companies.chatbot_type = "flow".
  • Flow engine: ms-communication — advances via the ai-next-node socket event.
  • AI routing: ms-ai POST /ask-flow (chatbot/chatbot.service.ts). See ms-ai/API_ENDPOINTS.md.
  • Handoff target: the Chat Agent (agents/ module) when handoff_to_ai is set.
  • Booking nodes: call the calendar integrations (Google / Calendly / GHL) — same tools the Call Agent uses (POST /tools/calendar/...).