From 12914dd447e215524c3976d3d5bc39dd74563342 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:14:09 +0530
Subject: [PATCH 1/2] feat(*): init the chatbot flow

---
 app/(main)/chatbot/page.tsx                   |  74 ++++++++
 app/api/chatbot/message/route.ts              |  23 +++
 app/components/Sidebar.tsx                    |   8 +-
 app/components/chatbot/ChatbotFlowCanvas.tsx  |  69 +++++++
 app/components/chatbot/ChatbotFlowContext.tsx |  23 +++
 app/components/chatbot/ChatbotTestPanel.tsx   | 119 ++++++++++++
 app/components/chatbot/LlmNode.tsx            |  88 +++++++++
 app/components/chatbot/LlmNodeAdvanced.tsx    |  63 +++++++
 app/components/chatbot/LlmNodePromptField.tsx |  73 +++++++
 app/components/chatbot/NodeFieldLabel.tsx     |  22 +++
 app/components/chatbot/TerminalNode.tsx       |  26 +++
 app/components/chatbot/flowHandleStyle.ts     |   9 +
 app/components/chatbot/index.ts               |   5 +
 app/components/icons/index.tsx                |   1 +
 app/components/icons/sidebar/FlowIcon.tsx     |  23 +++
 app/hooks/useChatbotFlow.ts                   | 130 +++++++++++++
 app/hooks/useChatbotTest.ts                   |  94 +++++++++
 app/lib/chatbotClient.ts                      |  26 +++
 app/lib/constants.ts                          |   4 +
 app/lib/modelSchema.ts                        |   2 +
 app/lib/navConfig.ts                          |   6 +
 app/lib/types/chatbot.ts                      |  45 +++++
 package-lock.json                             | 178 ++++++++++++++++++
 package.json                                  |   1 +
 24 files changed, 1107 insertions(+), 5 deletions(-)
 create mode 100644 app/(main)/chatbot/page.tsx
 create mode 100644 app/api/chatbot/message/route.ts
 create mode 100644 app/components/chatbot/ChatbotFlowCanvas.tsx
 create mode 100644 app/components/chatbot/ChatbotFlowContext.tsx
 create mode 100644 app/components/chatbot/ChatbotTestPanel.tsx
 create mode 100644 app/components/chatbot/LlmNode.tsx
 create mode 100644 app/components/chatbot/LlmNodeAdvanced.tsx
 create mode 100644 app/components/chatbot/LlmNodePromptField.tsx
 create mode 100644 app/components/chatbot/NodeFieldLabel.tsx
 create mode 100644 app/components/chatbot/TerminalNode.tsx
 create mode 100644 app/components/chatbot/flowHandleStyle.ts
 create mode 100644 app/components/chatbot/index.ts
 create mode 100644 app/components/icons/sidebar/FlowIcon.tsx
 create mode 100644 app/hooks/useChatbotFlow.ts
 create mode 100644 app/hooks/useChatbotTest.ts
 create mode 100644 app/lib/chatbotClient.ts
 create mode 100644 app/lib/types/chatbot.ts

diff --git a/app/(main)/chatbot/page.tsx b/app/(main)/chatbot/page.tsx
new file mode 100644
index 00000000..720f05b4
--- /dev/null
+++ b/app/(main)/chatbot/page.tsx
@@ -0,0 +1,74 @@
+/**
+ * Chatbot - Build a chatbot flow on a canvas and test each step live.
+ */
+
+"use client";
+
+import Sidebar from "@/app/components/Sidebar";
+import PageHeader from "@/app/components/PageHeader";
+import { Button } from "@/app/components/ui";
+import { PlusIcon } from "@/app/components/icons";
+import { ChatbotFlowCanvas, ChatbotTestPanel } from "@/app/components/chatbot";
+import { useApp } from "@/app/lib/context/AppContext";
+import { useChatbotFlow } from "@/app/hooks/useChatbotFlow";
+
+export default function ChatbotPage() {
+  const { sidebarCollapsed } = useApp();
+  const flow = useChatbotFlow();
+  const node = flow.selectedNode;
+
+  return (
+    <div className="w-full h-screen flex flex-col bg-bg-secondary">
+      <div className="flex flex-1 overflow-hidden">
+        <Sidebar collapsed={sidebarCollapsed} activeRoute="/chatbot" />
+
+        <div className="flex-1 flex flex-col overflow-hidden bg-bg-primary">
+          <PageHeader
+            title="Chatbot"
+            subtitle="Design a chatbot flow and test each step before saving"
+            actions={
+              <Button variant="outline" size="sm" onClick={flow.addNode}>
+                <PlusIcon className="w-3.5 h-3.5" />
+                Add step
+              </Button>
+            }
+          />
+
+          <div className="flex flex-1 min-h-0">
+            <div className="flex-1 min-w-0 bg-bg-primary">
+              <ChatbotFlowCanvas
+                nodes={flow.nodes}
+                edges={flow.edges}
+                onNodesChange={flow.onNodesChange}
+                onEdgesChange={flow.onEdgesChange}
+                onConnect={flow.onConnect}
+                onSelectNode={flow.setSelectedId}
+                updateNodeData={flow.updateNodeData}
+              />
+            </div>
+
+            <aside className="w-[380px] shrink-0 border-l border-border flex flex-col min-h-0 bg-bg-primary">
+              {node ? (
+                <>
+                  <div className="px-4 py-3 border-b border-border">
+                    <p className="text-sm font-semibold text-text-primary">
+                      Test: {node.data.label || "Untitled step"}
+                    </p>
+                    <p className="text-xs text-text-secondary">
+                      Click a step on the canvas to test it.
+                    </p>
+                  </div>
+                  <ChatbotTestPanel key={node.id} data={node.data} />
+                </>
+              ) : (
+                <div className="flex-1 flex items-center justify-center p-6 text-center text-sm text-text-secondary">
+                  Add a step to start testing.
+                </div>
+              )}
+            </aside>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/app/api/chatbot/message/route.ts b/app/api/chatbot/message/route.ts
new file mode 100644
index 00000000..15991d2a
--- /dev/null
+++ b/app/api/chatbot/message/route.ts
@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { apiClient } from "@/app/lib/apiClient";
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    const { status, data } = await apiClient(
+      request,
+      "/api/v1/chatbot/message",
+      { method: "POST", body: JSON.stringify(body) },
+    );
+    return NextResponse.json(data, { status });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        data: null,
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/app/components/Sidebar.tsx b/app/components/Sidebar.tsx
index db585568..2ef7443e 100644
--- a/app/components/Sidebar.tsx
+++ b/app/components/Sidebar.tsx
@@ -1,9 +1,5 @@
-/**
- * Sidebar  - Navigation sidebar with collapse/expand functionality
- * Provides hierarchical navigation with expandable submenus
- */
-
 "use client";
+
 import React, { useState, useEffect, useRef, useCallback } from "react";
 import { useRouter } from "next/navigation";
 import Image from "next/image";
@@ -20,6 +16,7 @@ import {
   ShieldCheckIcon,
   SlidersIcon,
   ChatIcon,
+  FlowIcon,
   ChartBarIcon,
   WarningTriangleIcon,
 } from "@/app/components/icons";
@@ -122,6 +119,7 @@ export default function Sidebar({
 
   const iconMap: Record<string, React.ReactNode> = {
     chat: <ChatIcon />,
+    flow: <FlowIcon />,
     clipboard: <ClipboardIcon />,
     document: <DocumentFileIcon />,
     book: <BookOpenIcon />,
diff --git a/app/components/chatbot/ChatbotFlowCanvas.tsx b/app/components/chatbot/ChatbotFlowCanvas.tsx
new file mode 100644
index 00000000..ed3f56f7
--- /dev/null
+++ b/app/components/chatbot/ChatbotFlowCanvas.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import { useMemo } from "react";
+import {
+  Background,
+  BackgroundVariant,
+  Connection,
+  Controls,
+  Edge,
+  EdgeChange,
+  NodeChange,
+  ReactFlow,
+} from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import LlmNode from "@/app/components/chatbot/LlmNode";
+import TerminalNode from "@/app/components/chatbot/TerminalNode";
+import { ChatbotFlowContext } from "@/app/components/chatbot/ChatbotFlowContext";
+import { ChatbotFlowNode, ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+const NODE_TYPES = {
+  llm: LlmNode,
+  flowInput: TerminalNode,
+  flowOutput: TerminalNode,
+};
+
+const DEFAULT_EDGE_OPTIONS = { style: { stroke: "#a3a3a3", strokeWidth: 1 } };
+
+interface ChatbotFlowCanvasProps {
+  nodes: ChatbotFlowNode[];
+  edges: Edge[];
+  onNodesChange: (changes: NodeChange<ChatbotFlowNode>[]) => void;
+  onEdgesChange: (changes: EdgeChange<Edge>[]) => void;
+  onConnect: (connection: Connection) => void;
+  onSelectNode: (id: string) => void;
+  updateNodeData: (id: string, patch: Partial<ChatbotNodeData>) => void;
+}
+
+export default function ChatbotFlowCanvas({
+  nodes,
+  edges,
+  onNodesChange,
+  onEdgesChange,
+  onConnect,
+  onSelectNode,
+  updateNodeData,
+}: ChatbotFlowCanvasProps) {
+  const contextValue = useMemo(() => ({ updateNodeData }), [updateNodeData]);
+
+  return (
+    <ChatbotFlowContext.Provider value={contextValue}>
+      <ReactFlow
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={NODE_TYPES}
+        defaultEdgeOptions={DEFAULT_EDGE_OPTIONS}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+        onConnect={onConnect}
+        onNodeClick={(_, node) => onSelectNode(node.id)}
+        fitView
+        fitViewOptions={{ maxZoom: 1, padding: 0.2 }}
+        proOptions={{ hideAttribution: true }}
+      >
+        <Background variant={BackgroundVariant.Dots} gap={16} size={1.5} />
+        <Controls />
+      </ReactFlow>
+    </ChatbotFlowContext.Provider>
+  );
+}
diff --git a/app/components/chatbot/ChatbotFlowContext.tsx b/app/components/chatbot/ChatbotFlowContext.tsx
new file mode 100644
index 00000000..9e49716a
--- /dev/null
+++ b/app/components/chatbot/ChatbotFlowContext.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import { ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+interface ChatbotFlowContextValue {
+  updateNodeData: (id: string, patch: Partial<ChatbotNodeData>) => void;
+}
+
+export const ChatbotFlowContext = createContext<ChatbotFlowContextValue | null>(
+  null,
+);
+
+/** Lets custom nodes edit their own data inline on the canvas. */
+export function useChatbotFlowContext(): ChatbotFlowContextValue {
+  const ctx = useContext(ChatbotFlowContext);
+  if (!ctx) {
+    throw new Error(
+      "useChatbotFlowContext must be used inside ChatbotFlowContext.Provider",
+    );
+  }
+  return ctx;
+}
diff --git a/app/components/chatbot/ChatbotTestPanel.tsx b/app/components/chatbot/ChatbotTestPanel.tsx
new file mode 100644
index 00000000..7884c61e
--- /dev/null
+++ b/app/components/chatbot/ChatbotTestPanel.tsx
@@ -0,0 +1,119 @@
+/**
+ * ChatbotTestPanel - Runs a throwaway test conversation against the selected
+ * node's current (unsaved) prompt and config.
+ */
+
+"use client";
+
+import { FormEvent, useEffect, useRef, useState } from "react";
+import { Button } from "@/app/components/ui";
+import { MarkdownContent } from "@/app/components/chat";
+import { RefreshIcon, SendIcon } from "@/app/components/icons";
+import { useChatbotTest } from "@/app/hooks/useChatbotTest";
+import { ChatbotMessage, ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+interface ChatbotTestPanelProps {
+  data: ChatbotNodeData;
+}
+
+function MessageBubble({ message }: { message: ChatbotMessage }) {
+  const isUser = message.role === "user";
+  return (
+    <div className={`flex ${isUser ? "justify-end" : "justify-start"}`}>
+      <div
+        className={`max-w-[85%] rounded-2xl px-3 py-2 text-sm ${
+          isUser
+            ? "bg-accent-primary text-white whitespace-pre-wrap"
+            : "bg-bg-secondary text-text-primary"
+        }`}
+      >
+        {isUser ? message.content : <MarkdownContent text={message.content} />}
+      </div>
+    </div>
+  );
+}
+
+export default function ChatbotTestPanel({ data }: ChatbotTestPanelProps) {
+  const { history, pendingMessage, isPending, canSend, send, reset } =
+    useChatbotTest(data);
+  const [input, setInput] = useState("");
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  const visible = history.filter((m) => m.role !== "system");
+  const hasStarted = history.length > 0;
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
+  }, [visible.length, pendingMessage, isPending]);
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault();
+    const text = input.trim();
+    if (!text || isPending) return;
+    setInput("");
+    const ok = await send(text);
+    if (!ok) setInput(text);
+  };
+
+  return (
+    <div className="flex flex-col flex-1 min-h-0">
+      <div className="flex-1 overflow-y-auto p-4 space-y-3">
+        {!hasStarted && !isPending && (
+          <div className="h-full flex flex-col items-center justify-center text-center gap-3">
+            <p className="text-sm text-text-secondary max-w-[260px]">
+              {canSend
+                ? "Start a test - the bot will send the first message."
+                : "Pick a configuration and write a system prompt to start testing."}
+            </p>
+            <Button size="sm" onClick={() => send()} disabled={!canSend}>
+              Start test
+            </Button>
+          </div>
+        )}
+        {visible.map((m, i) => (
+          <MessageBubble key={i} message={m} />
+        ))}
+        {pendingMessage && (
+          <MessageBubble message={{ role: "user", content: pendingMessage }} />
+        )}
+        {isPending && (
+          <p className="text-xs text-text-secondary animate-pulse">
+            Bot is typing…
+          </p>
+        )}
+        <div ref={bottomRef} />
+      </div>
+
+      {hasStarted && (
+        <form
+          onSubmit={handleSubmit}
+          className="border-t border-border p-3 flex items-center gap-2"
+        >
+          <button
+            type="button"
+            onClick={reset}
+            title="Restart test"
+            className="p-2 rounded-full text-text-secondary hover:bg-neutral-100 hover:text-text-primary cursor-pointer"
+          >
+            <RefreshIcon className="w-4 h-4" />
+          </button>
+          <input
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder="Reply as the user…"
+            disabled={isPending}
+            className="flex-1 px-3 py-2 rounded-full border border-border text-sm bg-bg-primary text-text-primary focus:outline-none focus:border-accent-primary disabled:opacity-60"
+          />
+          <button
+            type="submit"
+            disabled={isPending || !input.trim()}
+            title="Send"
+            className="p-2 rounded-full bg-accent-primary text-white hover:bg-accent-hover disabled:bg-neutral-200 disabled:text-text-secondary cursor-pointer disabled:cursor-not-allowed"
+          >
+            <SendIcon className="w-4 h-4" />
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}
diff --git a/app/components/chatbot/LlmNode.tsx b/app/components/chatbot/LlmNode.tsx
new file mode 100644
index 00000000..71c9c002
--- /dev/null
+++ b/app/components/chatbot/LlmNode.tsx
@@ -0,0 +1,88 @@
+/**
+ * LlmNode - Editable LLM step on the chatbot canvas: config, prompt and limits
+ * are edited inline, mirroring the node's data used by the test panel.
+ */
+
+"use client";
+
+import { Handle, NodeProps, Position } from "@xyflow/react";
+import { ChatConfigPicker } from "@/app/components/chat";
+import { ChatbotLlmNode, ChatbotNodeData } from "@/app/lib/types/chatbot";
+import { useChatbotFlowContext } from "@/app/components/chatbot/ChatbotFlowContext";
+import { FLOW_HANDLE_STYLE } from "@/app/components/chatbot/flowHandleStyle";
+import NodeFieldLabel from "@/app/components/chatbot/NodeFieldLabel";
+import LlmNodePromptField from "@/app/components/chatbot/LlmNodePromptField";
+import LlmNodeAdvanced from "@/app/components/chatbot/LlmNodeAdvanced";
+
+const PORT_LABEL_CLASS = "text-sm font-semibold font-mono text-text-primary";
+
+export default function LlmNode({
+  id,
+  data,
+  selected,
+}: NodeProps<ChatbotLlmNode>) {
+  const { updateNodeData } = useChatbotFlowContext();
+  const update = (patch: Partial<ChatbotNodeData>) => updateNodeData(id, patch);
+
+  return (
+    <div
+      className={`w-72 rounded-xl border bg-bg-primary shadow-md transition-colors ${
+        selected
+          ? "border-accent-primary ring-2 ring-accent-primary/20"
+          : "border-border"
+      }`}
+    >
+      <div className="relative px-4 pt-3 pb-1 text-center">
+        <input
+          value={data.label}
+          onChange={(e) => update({ label: e.target.value })}
+          placeholder="Untitled step"
+          className="nodrag w-full px-6 text-center text-base font-semibold text-text-primary bg-transparent focus:outline-none"
+        />
+        <p className="text-[11px] text-text-secondary truncate">{id}</p>
+      </div>
+
+      <div className="relative px-4 py-1">
+        <Handle
+          type="target"
+          position={Position.Left}
+          style={FLOW_HANDLE_STYLE}
+        />
+        <span className={PORT_LABEL_CLASS}>Input</span>
+      </div>
+
+      <div className="px-4 pt-2 pb-3 space-y-3">
+        <div className="nodrag nowheel">
+          <NodeFieldLabel
+            label="Configuration"
+            hint="Saved config and version used to call the model."
+          />
+          <ChatConfigPicker
+            configId={data.configId}
+            version={data.configVersion ?? 0}
+            onSelect={(configId, configVersion) =>
+              update({ configId, configVersion })
+            }
+            alignLeft
+          />
+        </div>
+
+        <LlmNodePromptField
+          value={data.systemPrompt}
+          onChange={(systemPrompt) => update({ systemPrompt })}
+        />
+
+        <LlmNodeAdvanced data={data} onChange={update} />
+      </div>
+
+      <div className="relative px-4 py-2.5 border-t-2 border-text-primary text-right">
+        <span className={PORT_LABEL_CLASS}>Output</span>
+        <Handle
+          type="source"
+          position={Position.Right}
+          style={FLOW_HANDLE_STYLE}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/app/components/chatbot/LlmNodeAdvanced.tsx b/app/components/chatbot/LlmNodeAdvanced.tsx
new file mode 100644
index 00000000..726f43c9
--- /dev/null
+++ b/app/components/chatbot/LlmNodeAdvanced.tsx
@@ -0,0 +1,63 @@
+/**
+ * LlmNodeAdvanced - Collapsible per-request limits for an LLM node.
+ */
+
+"use client";
+
+import { useState } from "react";
+import { Field } from "@/app/components/ui";
+import { ChevronDownIcon, ChevronUpIcon } from "@/app/components/icons";
+import { ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+interface LlmNodeAdvancedProps {
+  data: ChatbotNodeData;
+  onChange: (patch: Partial<ChatbotNodeData>) => void;
+}
+
+function toPositiveInt(value: string, fallback: number): number {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export default function LlmNodeAdvanced({
+  data,
+  onChange,
+}: LlmNodeAdvancedProps) {
+  const [open, setOpen] = useState(false);
+  const Chevron = open ? ChevronUpIcon : ChevronDownIcon;
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => setOpen((prev) => !prev)}
+        className="nodrag w-full flex items-center justify-center gap-1 py-1 text-xs font-semibold text-text-primary hover:text-accent-primary cursor-pointer"
+      >
+        Advanced
+        <Chevron className="w-3 h-3" />
+      </button>
+      {open && (
+        <div className="nodrag grid grid-cols-2 gap-2 pt-2">
+          <Field
+            label="Max tokens"
+            type="number"
+            value={String(data.maxTokens)}
+            onChange={(v) =>
+              onChange({ maxTokens: toPositiveInt(v, data.maxTokens) })
+            }
+          />
+          <Field
+            label="History token limit"
+            type="number"
+            value={String(data.historyTokenLimit)}
+            onChange={(v) =>
+              onChange({
+                historyTokenLimit: toPositiveInt(v, data.historyTokenLimit),
+              })
+            }
+          />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/app/components/chatbot/LlmNodePromptField.tsx b/app/components/chatbot/LlmNodePromptField.tsx
new file mode 100644
index 00000000..2b3755da
--- /dev/null
+++ b/app/components/chatbot/LlmNodePromptField.tsx
@@ -0,0 +1,73 @@
+/**
+ * LlmNodePromptField - Inline system-prompt editor with an expanded modal view.
+ */
+
+"use client";
+
+import { useState } from "react";
+import { createPortal } from "react-dom";
+import { Modal } from "@/app/components/ui";
+import { ExpandIcon } from "@/app/components/icons";
+import NodeFieldLabel from "@/app/components/chatbot/NodeFieldLabel";
+
+interface LlmNodePromptFieldProps {
+  value: string;
+  onChange: (value: string) => void;
+}
+
+const PLACEHOLDER =
+  "Goal: Register a student. Friendly, short WhatsApp messages, one question at a time.";
+
+export default function LlmNodePromptField({
+  value,
+  onChange,
+}: LlmNodePromptFieldProps) {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <div>
+      <NodeFieldLabel
+        label="Prompt"
+        hint="System prompt for this step. Editing it resets the test conversation."
+      >
+        <button
+          type="button"
+          onClick={() => setExpanded(true)}
+          title="Expand prompt"
+          className="nodrag text-text-primary hover:text-accent-primary cursor-pointer"
+        >
+          <ExpandIcon className="w-3.5 h-3.5" />
+        </button>
+      </NodeFieldLabel>
+      <textarea
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={PLACEHOLDER}
+        rows={4}
+        className="nodrag nowheel w-full px-2.5 py-2 rounded-md border border-border text-xs text-text-primary bg-bg-primary placeholder:text-neutral-400 resize-none focus:outline-none focus:border-accent-primary"
+      />
+
+      {/* Portaled: the canvas viewport is CSS-transformed, which breaks `fixed`. */}
+      {expanded &&
+        createPortal(
+          <Modal
+            open
+            onClose={() => setExpanded(false)}
+            title="Prompt"
+            maxWidth="max-w-3xl"
+          >
+            <div className="px-6 pb-6">
+              <textarea
+                value={value}
+                onChange={(e) => onChange(e.target.value)}
+                placeholder={PLACEHOLDER}
+                autoFocus
+                className="w-full h-[60vh] px-3 py-2 rounded-lg border border-border text-sm font-mono text-text-primary bg-bg-primary placeholder:text-neutral-400 resize-none focus:outline-none focus:border-accent-primary"
+              />
+            </div>
+          </Modal>,
+          document.body,
+        )}
+    </div>
+  );
+}
diff --git a/app/components/chatbot/NodeFieldLabel.tsx b/app/components/chatbot/NodeFieldLabel.tsx
new file mode 100644
index 00000000..b91427fc
--- /dev/null
+++ b/app/components/chatbot/NodeFieldLabel.tsx
@@ -0,0 +1,22 @@
+import { ReactNode } from "react";
+import { InfoTooltip } from "@/app/components/ui";
+
+interface NodeFieldLabelProps {
+  label: string;
+  hint: string;
+  children?: ReactNode;
+}
+
+export default function NodeFieldLabel({
+  label,
+  hint,
+  children,
+}: NodeFieldLabelProps) {
+  return (
+    <div className="flex items-center gap-2 mb-1.5">
+      <span className="text-xs font-semibold text-text-secondary">{label}</span>
+      {children}
+      <InfoTooltip text={hint} />
+    </div>
+  );
+}
diff --git a/app/components/chatbot/TerminalNode.tsx b/app/components/chatbot/TerminalNode.tsx
new file mode 100644
index 00000000..e6a95ba6
--- /dev/null
+++ b/app/components/chatbot/TerminalNode.tsx
@@ -0,0 +1,26 @@
+/**
+ * TerminalNode - Fixed "Input" / "Output" pill marking where the flow starts and ends.
+ */
+
+"use client";
+
+import { Handle, NodeProps, Position } from "@xyflow/react";
+import { ChatbotTerminalNode } from "@/app/lib/types/chatbot";
+import { FLOW_HANDLE_STYLE } from "@/app/components/chatbot/flowHandleStyle";
+
+export default function TerminalNode({
+  type,
+  data,
+}: NodeProps<ChatbotTerminalNode>) {
+  const isInput = type === "flowInput";
+  return (
+    <div className="px-4 py-2.5 rounded-lg border border-border bg-bg-primary shadow-sm text-sm font-semibold text-text-primary">
+      {data.label}
+      <Handle
+        type={isInput ? "source" : "target"}
+        position={isInput ? Position.Right : Position.Left}
+        style={FLOW_HANDLE_STYLE}
+      />
+    </div>
+  );
+}
diff --git a/app/components/chatbot/flowHandleStyle.ts b/app/components/chatbot/flowHandleStyle.ts
new file mode 100644
index 00000000..19915593
--- /dev/null
+++ b/app/components/chatbot/flowHandleStyle.ts
@@ -0,0 +1,9 @@
+import type { CSSProperties } from "react";
+
+/** Solid dark dot used for every connection handle on the chatbot canvas. */
+export const FLOW_HANDLE_STYLE: CSSProperties = {
+  width: 10,
+  height: 10,
+  background: "var(--color-text-primary)",
+  border: "none",
+};
diff --git a/app/components/chatbot/index.ts b/app/components/chatbot/index.ts
new file mode 100644
index 00000000..f4230108
--- /dev/null
+++ b/app/components/chatbot/index.ts
@@ -0,0 +1,5 @@
+export { default as ChatbotFlowCanvas } from "./ChatbotFlowCanvas";
+export { default as ChatbotTestPanel } from "./ChatbotTestPanel";
+export { default as LlmNode } from "./LlmNode";
+export { default as TerminalNode } from "./TerminalNode";
+export { ChatbotFlowContext } from "./ChatbotFlowContext";
diff --git a/app/components/icons/index.tsx b/app/components/icons/index.tsx
index d4b6d4d7..547487e6 100644
--- a/app/components/icons/index.tsx
+++ b/app/components/icons/index.tsx
@@ -53,6 +53,7 @@ export { default as ShieldCheckIcon } from "./sidebar/ShieldCheckIcon";
 export { default as LogoutIcon } from "./sidebar/LogoutIcon";
 export { default as AssessmentIcon } from "./sidebar/AssessmentIcon";
 export { default as ChatIcon } from "./sidebar/ChatIcon";
+export { default as FlowIcon } from "./sidebar/FlowIcon";
 export { default as SendIcon } from "./sidebar/SendIcon";
 export { default as ChartBarIcon } from "./sidebar/ChartBarIcon";
 
diff --git a/app/components/icons/sidebar/FlowIcon.tsx b/app/components/icons/sidebar/FlowIcon.tsx
new file mode 100644
index 00000000..feec5fa7
--- /dev/null
+++ b/app/components/icons/sidebar/FlowIcon.tsx
@@ -0,0 +1,23 @@
+interface IconProps {
+  className?: string;
+}
+
+export default function FlowIcon({ className }: IconProps) {
+  return (
+    <svg
+      className={`w-5 h-5 ${className ?? ""}`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth={2}
+    >
+      <rect x="3" y="3" width="7" height="5" rx="1.5" />
+      <rect x="14" y="16" width="7" height="5" rx="1.5" />
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M6.5 8v4a2 2 0 002 2h7a2 2 0 012 2"
+      />
+    </svg>
+  );
+}
diff --git a/app/hooks/useChatbotFlow.ts b/app/hooks/useChatbotFlow.ts
new file mode 100644
index 00000000..de75ff36
--- /dev/null
+++ b/app/hooks/useChatbotFlow.ts
@@ -0,0 +1,130 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import {
+  addEdge,
+  Connection,
+  Edge,
+  useEdgesState,
+  useNodesState,
+} from "@xyflow/react";
+import {
+  CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT,
+  CHATBOT_DEFAULT_MAX_TOKENS,
+} from "@/app/lib/constants";
+import {
+  ChatbotFlowNode,
+  ChatbotLlmNode,
+  ChatbotNodeData,
+} from "@/app/lib/types/chatbot";
+
+const INPUT_ID = "input";
+const OUTPUT_ID = "output";
+const LLM_ID_PREFIX = "LLMResponseWithPrompt";
+const INITIAL_LLM_ID = `${LLM_ID_PREFIX}-1`;
+
+function shortId(): string {
+  return Math.random().toString(16).slice(2, 7);
+}
+
+function createLlmNode(
+  position: { x: number; y: number },
+  label = "New step",
+  id = `${LLM_ID_PREFIX}-${shortId()}`,
+): ChatbotLlmNode {
+  return {
+    id,
+    type: "llm",
+    position,
+    data: {
+      label,
+      systemPrompt: "",
+      configId: "",
+      configVersion: undefined,
+      maxTokens: CHATBOT_DEFAULT_MAX_TOKENS,
+      historyTokenLimit: CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT,
+    },
+  };
+}
+
+function createInitialFlow(): { nodes: ChatbotFlowNode[]; edges: Edge[] } {
+  const llm = createLlmNode({ x: 260, y: 0 }, "Onboarding", INITIAL_LLM_ID);
+  return {
+    nodes: [
+      {
+        id: INPUT_ID,
+        type: "flowInput",
+        position: { x: 0, y: 55 },
+        data: { label: "Input" },
+        deletable: false,
+      },
+      llm,
+      {
+        id: OUTPUT_ID,
+        type: "flowOutput",
+        position: { x: 640, y: 270 },
+        data: { label: "Output" },
+        deletable: false,
+      },
+    ],
+    edges: [
+      { id: `${INPUT_ID}->${llm.id}`, source: INPUT_ID, target: llm.id },
+      { id: `${llm.id}->${OUTPUT_ID}`, source: llm.id, target: OUTPUT_ID },
+    ],
+  };
+}
+
+function isLlmNode(node: ChatbotFlowNode): node is ChatbotLlmNode {
+  return node.type === "llm";
+}
+
+/** Owns the in-memory (unsaved) chatbot flow graph and the node under test. */
+export function useChatbotFlow() {
+  const [initial] = useState(createInitialFlow);
+  const [nodes, setNodes, onNodesChange] = useNodesState<ChatbotFlowNode>(
+    initial.nodes,
+  );
+  const [edges, setEdges, onEdgesChange] = useEdgesState<Edge>(initial.edges);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const llmNodes = nodes.filter(isLlmNode);
+  // Fall back to the first LLM node so the test panel always has a target.
+  const selectedNode =
+    llmNodes.find((n) => n.id === selectedId) ?? llmNodes[0] ?? null;
+
+  const onConnect = useCallback(
+    (connection: Connection) => setEdges((eds) => addEdge(connection, eds)),
+    [setEdges],
+  );
+
+  const addNode = useCallback(() => {
+    const node = createLlmNode({ x: 260, y: 160 + llmNodes.length * 60 });
+    setNodes((prev) => [...prev, node]);
+    setSelectedId(node.id);
+  }, [llmNodes.length, setNodes]);
+
+  const updateNodeData = useCallback(
+    (id: string, patch: Partial<ChatbotNodeData>) => {
+      setNodes((prev) =>
+        prev.map((n) =>
+          n.id === id && isLlmNode(n)
+            ? { ...n, data: { ...n.data, ...patch } }
+            : n,
+        ),
+      );
+    },
+    [setNodes],
+  );
+
+  return {
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange,
+    onConnect,
+    selectedNode,
+    setSelectedId,
+    addNode,
+    updateNodeData,
+  };
+}
diff --git a/app/hooks/useChatbotTest.ts b/app/hooks/useChatbotTest.ts
new file mode 100644
index 00000000..5988fbb1
--- /dev/null
+++ b/app/hooks/useChatbotTest.ts
@@ -0,0 +1,94 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useAuth } from "@/app/lib/context/AuthContext";
+import { useToast } from "@/app/hooks/useToast";
+import { sendChatbotMessage } from "@/app/lib/chatbotClient";
+import { ChatbotMessage, ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+/**
+ * Drives the chatbot test panel for a single flow node. History lives only in
+ * React state; it is cleared whenever the node's prompt or config changes so
+ * every edit starts a fresh test.
+ */
+export function useChatbotTest(data: ChatbotNodeData) {
+  const { activeKey } = useAuth();
+  const apiKey = activeKey?.key ?? "";
+  const toast = useToast();
+
+  const [history, setHistory] = useState<ChatbotMessage[]>([]);
+  const [pendingMessage, setPendingMessage] = useState<string | null>(null);
+  const [isPending, setIsPending] = useState(false);
+
+  const resetKey = `${data.systemPrompt}\u0000${data.configId}\u0000${data.configVersion ?? ""}`;
+  const [prevResetKey, setPrevResetKey] = useState(resetKey);
+  if (prevResetKey !== resetKey) {
+    setPrevResetKey(resetKey);
+    setHistory([]);
+    setPendingMessage(null);
+    setIsPending(false);
+  }
+
+  // Bumped on every reset so responses from an outdated test are dropped.
+  const generationRef = useRef(0);
+  useEffect(() => {
+    generationRef.current += 1;
+  }, [resetKey]);
+
+  const canSend = !!data.configId && !!data.systemPrompt.trim();
+
+  const send = useCallback(
+    async (message?: string): Promise<boolean> => {
+      if (!data.configId) {
+        toast.error("Select a configuration and version first.");
+        return false;
+      }
+      if (!data.systemPrompt.trim()) {
+        toast.error("Add a system prompt to the node first.");
+        return false;
+      }
+
+      const generation = generationRef.current;
+      setIsPending(true);
+      setPendingMessage(message ?? null);
+      try {
+        const messages = await sendChatbotMessage(
+          {
+            config_id: data.configId,
+            config_version: data.configVersion,
+            system_prompt: data.systemPrompt,
+            history,
+            message,
+            max_tokens: data.maxTokens,
+            history_token_limit: data.historyTokenLimit,
+          },
+          apiKey,
+        );
+        if (generation !== generationRef.current) return false;
+        setHistory(messages);
+        return true;
+      } catch (err) {
+        if (generation !== generationRef.current) return false;
+        toast.error(
+          err instanceof Error ? err.message : "Something went wrong",
+        );
+        return false;
+      } finally {
+        if (generation === generationRef.current) {
+          setIsPending(false);
+          setPendingMessage(null);
+        }
+      }
+    },
+    [apiKey, data, history, toast],
+  );
+
+  const reset = useCallback(() => {
+    generationRef.current += 1;
+    setHistory([]);
+    setPendingMessage(null);
+    setIsPending(false);
+  }, []);
+
+  return { history, pendingMessage, isPending, canSend, send, reset };
+}
diff --git a/app/lib/chatbotClient.ts b/app/lib/chatbotClient.ts
new file mode 100644
index 00000000..d7ece704
--- /dev/null
+++ b/app/lib/chatbotClient.ts
@@ -0,0 +1,26 @@
+import { apiFetch } from "@/app/lib/apiClient";
+import {
+  ChatbotMessage,
+  ChatbotMessageRequest,
+  ChatbotMessageResponse,
+} from "@/app/lib/types/chatbot";
+
+/**
+ * Sends one turn of a chatbot test conversation. The backend is stateless:
+ * it takes the full history and returns the updated history (old messages
+ * plus the new user/assistant turn).
+ */
+export async function sendChatbotMessage(
+  body: ChatbotMessageRequest,
+  apiKey: string,
+): Promise<ChatbotMessage[]> {
+  const res = await apiFetch<ChatbotMessageResponse>(
+    "/api/chatbot/message",
+    apiKey,
+    { method: "POST", body: JSON.stringify(body) },
+  );
+  if (!res.success || !res.data?.messages) {
+    throw new Error(res.error || "Failed to get a response from the chatbot.");
+  }
+  return res.data.messages;
+}
diff --git a/app/lib/constants.ts b/app/lib/constants.ts
index 8927babc..0a32cebd 100644
--- a/app/lib/constants.ts
+++ b/app/lib/constants.ts
@@ -213,3 +213,7 @@ export const PAGER_BUTTON_IDLE =
   "border-border bg-bg-primary text-text-secondary hover:border-accent-muted hover:text-text-primary";
 export const PAGER_BUTTON_CURRENT =
   "border-accent-primary bg-accent-primary text-white font-semibold";
+
+/** Chatbot flow — default per-request limits for the test panel. */
+export const CHATBOT_DEFAULT_MAX_TOKENS = 2048;
+export const CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT = 6000;
diff --git a/app/lib/modelSchema.ts b/app/lib/modelSchema.ts
index 375adfb2..3070981e 100644
--- a/app/lib/modelSchema.ts
+++ b/app/lib/modelSchema.ts
@@ -23,6 +23,7 @@ export const SUPPORTED_PROVIDERS = [
   "openai",
   "google",
   "google-aistudio",
+  "anthropic",
 ] as const;
 
 export const SUPPORTED_PARAMS = new Set([
@@ -85,6 +86,7 @@ export const PARAM_VALUE_LABELS: Record<string, Record<string, string>> = {
     medium: "Medium",
     high: "High",
     xhigh: "Extra High",
+    max: "Max",
   },
 };
 
diff --git a/app/lib/navConfig.ts b/app/lib/navConfig.ts
index 63442573..c608682a 100644
--- a/app/lib/navConfig.ts
+++ b/app/lib/navConfig.ts
@@ -48,6 +48,12 @@ export const NAV_ITEMS: NavItemConfig[] = [
     gateDescription:
       "Log in to chat with your assistants and keep conversation history.",
   },
+  {
+    name: "Chatbot",
+    route: "/chatbot",
+    icon: "flow",
+    gateDescription: "Log in to build and test chatbot flows.",
+  },
   {
     name: "Evaluations",
     icon: "clipboard",
diff --git a/app/lib/types/chatbot.ts b/app/lib/types/chatbot.ts
new file mode 100644
index 00000000..5cadcde0
--- /dev/null
+++ b/app/lib/types/chatbot.ts
@@ -0,0 +1,45 @@
+import type { Node } from "@xyflow/react";
+
+export type ChatbotRole = "system" | "user" | "assistant";
+
+export interface ChatbotMessage {
+  role: ChatbotRole;
+  content: string;
+}
+
+/** Data carried by each LLM node on the flow canvas (unsaved, in-memory). */
+export type ChatbotNodeData = {
+  label: string;
+  systemPrompt: string;
+  configId: string;
+  configVersion?: number;
+  maxTokens: number;
+  historyTokenLimit: number;
+};
+
+export type ChatbotLlmNode = Node<ChatbotNodeData, "llm">;
+
+/** Fixed entry/exit points of the flow. */
+export type ChatbotTerminalNode = Node<
+  { label: string },
+  "flowInput" | "flowOutput"
+>;
+
+export type ChatbotFlowNode = ChatbotLlmNode | ChatbotTerminalNode;
+
+export interface ChatbotMessageRequest {
+  config_id: string;
+  config_version?: number;
+  system_prompt: string;
+  history: ChatbotMessage[];
+  /** Omitted on the first call so the bot greets first. */
+  message?: string;
+  max_tokens?: number;
+  history_token_limit?: number;
+}
+
+export interface ChatbotMessageResponse {
+  success: boolean;
+  data?: { messages: ChatbotMessage[] } | null;
+  error?: string | null;
+}
diff --git a/package-lock.json b/package-lock.json
index ec0ed31c..c8759fcd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,9 +7,11 @@
     "": {
       "name": "kaapi-frontend",
       "version": "0.1.0",
+      "license": "AGPL-3.0-or-later",
       "dependencies": {
         "@react-oauth/google": "^0.13.4",
         "@univerjs/presets": "^0.23.0",
+        "@xyflow/react": "^12.12.0",
         "date-fns": "^4.1.0",
         "date-fns-tz": "^3.2.0",
         "highlight.js": "^11.11.1",
@@ -2477,6 +2479,15 @@
       "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
       "license": "MIT"
     },
+    "node_modules/@types/d3-drag": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
+      "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
     "node_modules/@types/d3-ease": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
@@ -2507,6 +2518,12 @@
         "@types/d3-time": "*"
       }
     },
+    "node_modules/@types/d3-selection": {
+      "version": "3.0.12",
+      "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.12.tgz",
+      "integrity": "sha512-Qe/KWYhEiIIxGs7HrAAjMfShxKldx19SJtr5zu53f3afPsdZNz7HHtdTLXo/kqeiWNXVycI24kSnfzBYkTzpgw==",
+      "license": "MIT"
+    },
     "node_modules/@types/d3-shape": {
       "version": "3.1.8",
       "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.8.tgz",
@@ -2528,6 +2545,25 @@
       "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
       "license": "MIT"
     },
+    "node_modules/@types/d3-transition": {
+      "version": "3.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
+      "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-zoom": {
+      "version": "3.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.9.tgz",
+      "integrity": "sha512-0sE1406XBYJGiqD3AusTl9ZqC//2mIXix51tbom25gDCA8ri4xnSZg28CaSE8Srl6FClqABUKfsn0qghgdepMA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-interpolate": "*",
+        "@types/d3-selection": "*"
+      }
+    },
     "node_modules/@types/debug": {
       "version": "4.1.13",
       "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
@@ -5318,6 +5354,76 @@
         }
       }
     },
+    "node_modules/@xyflow/react": {
+      "version": "12.12.0",
+      "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.12.0.tgz",
+      "integrity": "sha512-74oXI0Rgm1Eu33cHQAd74J6oVgCH9mbFyTVQbsGgp2kmWwh0HdtBr2VP04z8mbPD+M/xO69nqG5dDEt7/EN2rQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@xyflow/system": "0.0.83",
+        "classcat": "^5.0.3",
+        "zustand": "^4.4.0"
+      },
+      "peerDependencies": {
+        "@types/react": ">=17",
+        "@types/react-dom": ">=17",
+        "react": ">=17",
+        "react-dom": ">=17"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@xyflow/react/node_modules/zustand": {
+      "version": "4.5.7",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
+      "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+      "license": "MIT",
+      "dependencies": {
+        "use-sync-external-store": "^1.2.2"
+      },
+      "engines": {
+        "node": ">=12.7.0"
+      },
+      "peerDependencies": {
+        "@types/react": ">=16.8",
+        "immer": ">=9.0.6",
+        "react": ">=16.8"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "immer": {
+          "optional": true
+        },
+        "react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@xyflow/system": {
+      "version": "0.0.83",
+      "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.83.tgz",
+      "integrity": "sha512-a//eDjez3WZF47aaPTfVUDD0OINOq+WVwBZCRTqG+m0a5euX8EwlJ4jMY1Wxz0Ocj4xOeekJ70V22Pq0ll8RJw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-drag": "^3.0.7",
+        "@types/d3-interpolate": "^3.0.4",
+        "@types/d3-selection": "^3.0.10",
+        "@types/d3-transition": "^3.0.8",
+        "@types/d3-zoom": "^3.0.8",
+        "d3-drag": "^3.0.0",
+        "d3-interpolate": "^3.0.1",
+        "d3-selection": "^3.0.0",
+        "d3-zoom": "^3.0.0"
+      }
+    },
     "node_modules/acorn": {
       "version": "8.15.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
@@ -5932,6 +6038,12 @@
         "url": "https://polar.sh/cva"
       }
     },
+    "node_modules/classcat": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
+      "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
+      "license": "MIT"
+    },
     "node_modules/cli-cursor": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz",
@@ -6164,6 +6276,28 @@
         "node": ">=12"
       }
     },
+    "node_modules/d3-dispatch": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+      "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-drag": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
+      "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-selection": "3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/d3-ease": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
@@ -6219,6 +6353,15 @@
         "node": ">=12"
       }
     },
+    "node_modules/d3-selection": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
+      "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/d3-shape": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
@@ -6264,6 +6407,41 @@
         "node": ">=12"
       }
     },
+    "node_modules/d3-transition": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
+      "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3",
+        "d3-dispatch": "1 - 3",
+        "d3-ease": "1 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-timer": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "peerDependencies": {
+        "d3-selection": "2 - 3"
+      }
+    },
+    "node_modules/d3-zoom": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
+      "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-drag": "2 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-selection": "2 - 3",
+        "d3-transition": "2 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/damerau-levenshtein": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz",
diff --git a/package.json b/package.json
index 6d7d7370..8749b708 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,7 @@
   "dependencies": {
     "@react-oauth/google": "^0.13.4",
     "@univerjs/presets": "^0.23.0",
+    "@xyflow/react": "^12.12.0",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
     "highlight.js": "^11.11.1",

From 33517dfecba5f8630c0f3eb1a2d49ff0604396b4 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Fri, 23 Oct 2026 00:44:28 +0530
Subject: [PATCH 2/2] fix: implement the state management api flow creation

---
 .env.example                                  |   2 +
 app/(main)/chatbot/page.tsx                   | 106 ++++++--
 app/api/chatbot/message/route.ts              |  23 --
 .../sessions/[session_id]/message/route.ts    |  48 ++++
 app/api/chatbot/sessions/route.ts             |  31 +++
 .../evaluations/[id]/improve-prompt/route.ts  |  26 +-
 app/api/webhooks/chatbot/route.ts             |  56 +++++
 app/api/webhooks/chatbot/stream/route.ts      |  82 +++++++
 app/api/webhooks/prompt-improvement/route.ts  |  11 +-
 app/components/chatbot/ChatbotChatInput.tsx   |  50 ++++
 app/components/chatbot/ChatbotFlowCanvas.tsx  |   3 -
 .../chatbot/ChatbotMessageBubble.tsx          |  23 ++
 app/components/chatbot/ChatbotSessionInfo.tsx |  45 ++++
 app/components/chatbot/ChatbotTestPanel.tsx   | 189 ++++++++-------
 app/components/chatbot/LlmNode.tsx            |  18 +-
 app/components/chatbot/LlmNodeAdvanced.tsx    |  63 -----
 app/hooks/useChatbotFlow.ts                   | 122 ++++++----
 app/hooks/useChatbotPendingReply.ts           |  39 +++
 app/hooks/useChatbotReplyStream.ts            |  43 ++++
 app/hooks/useChatbotSession.ts                | 228 ++++++++++++++++++
 app/hooks/useChatbotTest.ts                   |  94 --------
 app/hooks/useConfigs.ts                       |   6 +-
 app/lib/chatbotClient.ts                      |  73 ++++--
 app/lib/constants.ts                          |  11 +-
 app/lib/store/chatbot.ts                      |  91 +++++++
 app/lib/store/chatbotSessionStore.ts          |  97 ++++++++
 app/lib/types/chatbot.ts                      |  99 ++++++--
 app/lib/types/webhookSecret.ts                |   6 +-
 app/lib/utils/chatbotSessionCookie.ts         |  15 ++
 app/lib/webhookCallback.ts                    |  37 +++
 app/lib/webhookSecret.ts                      |   8 +-
 31 files changed, 1319 insertions(+), 426 deletions(-)
 delete mode 100644 app/api/chatbot/message/route.ts
 create mode 100644 app/api/chatbot/sessions/[session_id]/message/route.ts
 create mode 100644 app/api/chatbot/sessions/route.ts
 create mode 100644 app/api/webhooks/chatbot/route.ts
 create mode 100644 app/api/webhooks/chatbot/stream/route.ts
 create mode 100644 app/components/chatbot/ChatbotChatInput.tsx
 create mode 100644 app/components/chatbot/ChatbotMessageBubble.tsx
 create mode 100644 app/components/chatbot/ChatbotSessionInfo.tsx
 delete mode 100644 app/components/chatbot/LlmNodeAdvanced.tsx
 create mode 100644 app/hooks/useChatbotPendingReply.ts
 create mode 100644 app/hooks/useChatbotReplyStream.ts
 create mode 100644 app/hooks/useChatbotSession.ts
 delete mode 100644 app/hooks/useChatbotTest.ts
 create mode 100644 app/lib/store/chatbot.ts
 create mode 100644 app/lib/store/chatbotSessionStore.ts
 create mode 100644 app/lib/utils/chatbotSessionCookie.ts
 create mode 100644 app/lib/webhookCallback.ts

diff --git a/.env.example b/.env.example
index 09d3f15b..8d0346eb 100644
--- a/.env.example
+++ b/.env.example
@@ -2,3 +2,5 @@ BACKEND_URL=http://localhost:8000
 GUARDRAILS_URL = http://localhost:8001
 GUARDRAILS_TOKEN =
 NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+NEXT_PUBLIC_APP_URL=https://your-public-app-url.example.com
+WEBHOOK_SECRET=
diff --git a/app/(main)/chatbot/page.tsx b/app/(main)/chatbot/page.tsx
index 720f05b4..92b7f3d1 100644
--- a/app/(main)/chatbot/page.tsx
+++ b/app/(main)/chatbot/page.tsx
@@ -1,21 +1,72 @@
 /**
- * Chatbot - Build a chatbot flow on a canvas and test each step live.
+ * Chatbot - Design the chatbot flow on a canvas; Save stores it as a
+ * server-side session that the test panel chats with.
  */
 
 "use client";
 
+import { useCallback, useEffect } from "react";
 import Sidebar from "@/app/components/Sidebar";
 import PageHeader from "@/app/components/PageHeader";
 import { Button } from "@/app/components/ui";
-import { PlusIcon } from "@/app/components/icons";
 import { ChatbotFlowCanvas, ChatbotTestPanel } from "@/app/components/chatbot";
 import { useApp } from "@/app/lib/context/AppContext";
+import { useToast } from "@/app/hooks/useToast";
 import { useChatbotFlow } from "@/app/hooks/useChatbotFlow";
+import { useChatbotSession } from "@/app/hooks/useChatbotSession";
+import { useChatbotStore } from "@/app/lib/store/chatbot";
+import { ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+function validateFlow(data: ChatbotNodeData): string | null {
+  if (!data.configId) return "Select a configuration and version first.";
+  if (!data.systemPrompt.trim()) return "Add a prompt before saving.";
+  return null;
+}
 
 export default function ChatbotPage() {
   const { sidebarCollapsed } = useApp();
+  const toast = useToast();
   const flow = useChatbotFlow();
-  const node = flow.selectedNode;
+  const session = useChatbotSession();
+  const savedFlow = useChatbotStore((s) => s.savedFlow);
+
+  // Trigger persisted-state rehydration on mount.
+  useEffect(() => {
+    useChatbotStore.persist.rehydrate();
+  }, []);
+
+  const createSessionFor = useCallback(
+    async (data: ChatbotNodeData): Promise<boolean> => {
+      const error = validateFlow(data);
+      if (error) {
+        toast.error(error);
+        return false;
+      }
+      return session.startSession(data);
+    },
+    [session, toast],
+  );
+
+  const handleSave = async () => {
+    if (!flow.llmNode) return;
+    const data = flow.llmNode.data;
+    if (await createSessionFor(data)) {
+      flow.markSaved(data);
+      toast.success("Flow saved. A new chat session has started.");
+    }
+  };
+
+  const handleRestart = async () => {
+    if (!savedFlow) {
+      toast.error("Save the flow first to start a session.");
+      return;
+    }
+    if (await createSessionFor(savedFlow)) {
+      toast.success("New chat session started.");
+    }
+  };
+
+  const canEdit = flow.isDirty && !session.isCreating;
 
   return (
     <div className="w-full h-screen flex flex-col bg-bg-secondary">
@@ -25,12 +76,21 @@ export default function ChatbotPage() {
         <div className="flex-1 flex flex-col overflow-hidden bg-bg-primary">
           <PageHeader
             title="Chatbot"
-            subtitle="Design a chatbot flow and test each step before saving"
+            subtitle="Design a chatbot flow, save it and test it live"
             actions={
-              <Button variant="outline" size="sm" onClick={flow.addNode}>
-                <PlusIcon className="w-3.5 h-3.5" />
-                Add step
-              </Button>
+              <div className="flex items-center gap-2">
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={flow.discard}
+                  disabled={!canEdit}
+                >
+                  Discard changes
+                </Button>
+                <Button size="sm" onClick={handleSave} disabled={!canEdit}>
+                  {session.isCreating ? "Saving…" : "Save"}
+                </Button>
+              </div>
             }
           />
 
@@ -42,29 +102,23 @@ export default function ChatbotPage() {
                 onNodesChange={flow.onNodesChange}
                 onEdgesChange={flow.onEdgesChange}
                 onConnect={flow.onConnect}
-                onSelectNode={flow.setSelectedId}
                 updateNodeData={flow.updateNodeData}
               />
             </div>
 
             <aside className="w-[380px] shrink-0 border-l border-border flex flex-col min-h-0 bg-bg-primary">
-              {node ? (
-                <>
-                  <div className="px-4 py-3 border-b border-border">
-                    <p className="text-sm font-semibold text-text-primary">
-                      Test: {node.data.label || "Untitled step"}
-                    </p>
-                    <p className="text-xs text-text-secondary">
-                      Click a step on the canvas to test it.
-                    </p>
-                  </div>
-                  <ChatbotTestPanel key={node.id} data={node.data} />
-                </>
-              ) : (
-                <div className="flex-1 flex items-center justify-center p-6 text-center text-sm text-text-secondary">
-                  Add a step to start testing.
-                </div>
-              )}
+              <ChatbotTestPanel
+                hasSession={!!session.sessionId}
+                sessionName={session.sessionName}
+                status={session.status}
+                completionStatus={session.completionStatus}
+                messages={session.messages}
+                isPending={session.isPending}
+                isRestarting={session.isCreating}
+                isDirty={flow.isDirty}
+                onSend={session.send}
+                onRestart={handleRestart}
+              />
             </aside>
           </div>
         </div>
diff --git a/app/api/chatbot/message/route.ts b/app/api/chatbot/message/route.ts
deleted file mode 100644
index 15991d2a..00000000
--- a/app/api/chatbot/message/route.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { NextResponse } from "next/server";
-import { apiClient } from "@/app/lib/apiClient";
-
-export async function POST(request: Request) {
-  try {
-    const body = await request.json();
-    const { status, data } = await apiClient(
-      request,
-      "/api/v1/chatbot/message",
-      { method: "POST", body: JSON.stringify(body) },
-    );
-    return NextResponse.json(data, { status });
-  } catch (error) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        data: null,
-      },
-      { status: 500 },
-    );
-  }
-}
diff --git a/app/api/chatbot/sessions/[session_id]/message/route.ts b/app/api/chatbot/sessions/[session_id]/message/route.ts
new file mode 100644
index 00000000..40aeb0fc
--- /dev/null
+++ b/app/api/chatbot/sessions/[session_id]/message/route.ts
@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server";
+import { proxyErrorResponse, proxyJsonResponse } from "@/app/api/_routeProxy";
+import { buildWebhookCallbackUrl } from "@/app/lib/webhookCallback";
+
+/**
+ * Queues one chatbot turn. The browser only sends `message`; the webhook URL
+ * (with its secret) is added here so it never reaches the client.
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ session_id: string }> },
+) {
+  const { session_id } = await params;
+
+  let webhookUrl: string;
+  try {
+    webhookUrl = buildWebhookCallbackUrl(request, "/api/webhooks/chatbot");
+  } catch (error) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: `Webhook is not configured: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      },
+      { status: 500 },
+    );
+  }
+
+  try {
+    const body = (await request.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    return await proxyJsonResponse(
+      request,
+      `/api/v1/chatbot/sessions/${encodeURIComponent(session_id)}/message`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          ...(body.message ? { message: body.message } : {}),
+          webhook_url: webhookUrl,
+        }),
+      },
+    );
+  } catch (error) {
+    return proxyErrorResponse("chatbot send-message error:", error);
+  }
+}
diff --git a/app/api/chatbot/sessions/route.ts b/app/api/chatbot/sessions/route.ts
new file mode 100644
index 00000000..011cdcbe
--- /dev/null
+++ b/app/api/chatbot/sessions/route.ts
@@ -0,0 +1,31 @@
+import { NextRequest } from "next/server";
+import {
+  proxyErrorResponse,
+  proxyJsonResponse,
+  withQueryParams,
+} from "@/app/api/_routeProxy";
+
+/** Creates a chatbot session (stores the prompt + config pin server-side). */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    return await proxyJsonResponse(request, "/api/v1/chatbot/sessions", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  } catch (error) {
+    return proxyErrorResponse("chatbot create-session error:", error);
+  }
+}
+
+/** Latest session for a `contact_ref`. */
+export async function GET(request: NextRequest) {
+  try {
+    return await proxyJsonResponse(
+      request,
+      withQueryParams("/api/v1/chatbot/sessions", request.nextUrl.searchParams),
+    );
+  } catch (error) {
+    return proxyErrorResponse("chatbot get-session error:", error);
+  }
+}
diff --git a/app/api/evaluations/[id]/improve-prompt/route.ts b/app/api/evaluations/[id]/improve-prompt/route.ts
index ca9f4ceb..0f808fa6 100644
--- a/app/api/evaluations/[id]/improve-prompt/route.ts
+++ b/app/api/evaluations/[id]/improve-prompt/route.ts
@@ -1,28 +1,9 @@
 import { NextRequest, NextResponse } from "next/server";
 import { apiClient } from "@/app/lib/apiClient";
 import { markJobPending } from "@/app/lib/store/promptImprovementStore";
-import { readWebhookSecret } from "@/app/lib/webhookSecret";
+import { buildWebhookCallbackUrl } from "@/app/lib/webhookCallback";
 import type { LLMJobImmediatePublic } from "@/app/lib/types/promptImprovement";
 
-function resolveCallbackUrl(request: NextRequest): string {
-  const secretResult = readWebhookSecret();
-  if (!secretResult.ok || !secretResult.secret) {
-    throw new Error(
-      secretResult.reason ?? "prompt_improvement_webhook_secret_missing",
-    );
-  }
-  const configured =
-    process.env.NEXT_PUBLIC_APP_URL ?? process.env.APP_URL ?? null;
-  const base = configured
-    ? configured.replace(/\/$/, "")
-    : `${request.headers.get("x-forwarded-proto") ?? "https"}://${
-        request.headers.get("x-forwarded-host") ??
-        request.headers.get("host") ??
-        request.nextUrl.host
-      }`;
-  return `${base}/api/webhooks/prompt-improvement?secret_value=${encodeURIComponent(secretResult.secret)}`;
-}
-
 export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> },
@@ -31,7 +12,10 @@ export async function POST(
     const { id } = await params;
 
     const payload = {
-      callback_url: resolveCallbackUrl(request),
+      callback_url: buildWebhookCallbackUrl(
+        request,
+        "/api/webhooks/prompt-improvement",
+      ),
     };
 
     const { status, data } = await apiClient(
diff --git a/app/api/webhooks/chatbot/route.ts b/app/api/webhooks/chatbot/route.ts
new file mode 100644
index 00000000..e29e3d96
--- /dev/null
+++ b/app/api/webhooks/chatbot/route.ts
@@ -0,0 +1,56 @@
+import { NextRequest, NextResponse } from "next/server";
+import { saveSessionEvent } from "@/app/lib/store/chatbotSessionStore";
+import { isWebhookAuthorized } from "@/app/lib/webhookCallback";
+import type {
+  ChatbotSessionEvent,
+  ChatbotWebhookPayload,
+} from "@/app/lib/types/chatbot";
+
+function toSessionEvent(
+  body: ChatbotWebhookPayload,
+): Omit<ChatbotSessionEvent, "seq"> | null {
+  const data = body.data;
+  if (!data?.session_id) return null;
+  return {
+    sessionId: data.session_id,
+    success: body.success === true,
+    reply: data.reply ?? null,
+    status: data.status ?? null,
+    completionStatus: data.completion_status ?? null,
+    collectedFields: data.collected_fields ?? null,
+    error: body.error ?? null,
+  };
+}
+
+/** Receives a completed chatbot turn from Kaapi and hands it to open streams. */
+export async function POST(request: NextRequest) {
+  try {
+    if (!isWebhookAuthorized(request)) {
+      return NextResponse.json(
+        { success: false, error: "unauthorized" },
+        { status: 401 },
+      );
+    }
+    const event = toSessionEvent(
+      (await request.json()) as ChatbotWebhookPayload,
+    );
+    if (!event) {
+      return NextResponse.json(
+        { success: false, error: "invalid_payload" },
+        { status: 400 },
+      );
+    }
+    saveSessionEvent(event);
+    return NextResponse.json({ success: true, data: { received: true } });
+  } catch (error) {
+    console.error("chatbot webhook error:", error);
+    return NextResponse.json(
+      {
+        success: false,
+        error:
+          error instanceof Error ? error.message : "webhook_processing_failed",
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/app/api/webhooks/chatbot/stream/route.ts b/app/api/webhooks/chatbot/stream/route.ts
new file mode 100644
index 00000000..e61b6418
--- /dev/null
+++ b/app/api/webhooks/chatbot/stream/route.ts
@@ -0,0 +1,82 @@
+import { NextRequest } from "next/server";
+import {
+  getSessionEventsAfter,
+  subscribeSessionEvents,
+} from "@/app/lib/store/chatbotSessionStore";
+import type { ChatbotSessionEvent } from "@/app/lib/types/chatbot";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const HEARTBEAT_MS = 20_000;
+
+function parseSeq(value: string | null): number {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * SSE stream of webhook replies for one chatbot session. Each event carries
+ * its `seq` as the SSE id, so a reconnecting EventSource resumes via
+ * `Last-Event-ID`; `after` lets a fresh page load skip replies it already has.
+ */
+export async function GET(request: NextRequest) {
+  const sessionId = request.nextUrl.searchParams.get("session_id");
+  if (!sessionId) {
+    return new Response("session_id_required", { status: 400 });
+  }
+  const afterSeq = Math.max(
+    parseSeq(request.nextUrl.searchParams.get("after")),
+    parseSeq(request.headers.get("last-event-id")),
+  );
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      const push = (event: ChatbotSessionEvent) => {
+        try {
+          controller.enqueue(
+            encoder.encode(
+              `id: ${event.seq}\nevent: reply\ndata: ${JSON.stringify(event)}\n\n`,
+            ),
+          );
+        } catch {
+          // stream closed
+        }
+      };
+
+      // Subscribe before replaying so nothing slips in between.
+      const unsubscribe = subscribeSessionEvents(sessionId, push);
+      getSessionEventsAfter(sessionId, afterSeq).forEach(push);
+
+      const heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(`: ping\n\n`));
+        } catch {
+          finish();
+        }
+      }, HEARTBEAT_MS);
+
+      function finish() {
+        clearInterval(heartbeat);
+        unsubscribe();
+        try {
+          controller.close();
+        } catch {
+          // already closed
+        }
+      }
+
+      request.signal.addEventListener("abort", finish);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
diff --git a/app/api/webhooks/prompt-improvement/route.ts b/app/api/webhooks/prompt-improvement/route.ts
index 8fe0ea9b..fa252033 100644
--- a/app/api/webhooks/prompt-improvement/route.ts
+++ b/app/api/webhooks/prompt-improvement/route.ts
@@ -3,19 +3,12 @@ import {
   getJobSnapshot,
   saveJobSnapshot,
 } from "@/app/lib/store/promptImprovementStore";
-import { readWebhookSecret } from "@/app/lib/webhookSecret";
+import { isWebhookAuthorized } from "@/app/lib/webhookCallback";
 import type { PromptImprovementJobPublic } from "@/app/lib/types/promptImprovement";
 
-function isAuthorized(request: NextRequest): boolean {
-  const secretResult = readWebhookSecret();
-  if (!secretResult.ok || !secretResult.secret) return false;
-  const provided = request.nextUrl.searchParams.get("secret_value");
-  return provided === secretResult.secret;
-}
-
 export async function POST(request: NextRequest) {
   try {
-    if (!isAuthorized(request)) {
+    if (!isWebhookAuthorized(request)) {
       return NextResponse.json(
         { success: false, error: "unauthorized" },
         { status: 401 },
diff --git a/app/components/chatbot/ChatbotChatInput.tsx b/app/components/chatbot/ChatbotChatInput.tsx
new file mode 100644
index 00000000..8ed3de6c
--- /dev/null
+++ b/app/components/chatbot/ChatbotChatInput.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import { FormEvent, useState } from "react";
+import { SendIcon } from "@/app/components/icons";
+
+interface ChatbotChatInputProps {
+  disabled: boolean;
+  placeholder: string;
+  /** Resolves false when sending failed, so the draft is restored. */
+  onSend: (message: string) => Promise<boolean>;
+}
+
+export default function ChatbotChatInput({
+  disabled,
+  placeholder,
+  onSend,
+}: ChatbotChatInputProps) {
+  const [input, setInput] = useState("");
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault();
+    const text = input.trim();
+    if (!text || disabled) return;
+    setInput("");
+    if (!(await onSend(text))) setInput(text);
+  };
+
+  return (
+    <form
+      onSubmit={handleSubmit}
+      className="border-t border-border p-3 flex items-center gap-2"
+    >
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        placeholder={placeholder}
+        disabled={disabled}
+        className="flex-1 px-3 py-2 rounded-full border border-border text-sm bg-bg-primary text-text-primary focus:outline-none focus:border-accent-primary disabled:opacity-60"
+      />
+      <button
+        type="submit"
+        disabled={disabled || !input.trim()}
+        title="Send"
+        className="p-2 rounded-full bg-accent-primary text-white hover:bg-accent-hover disabled:bg-neutral-200 disabled:text-text-secondary cursor-pointer disabled:cursor-not-allowed"
+      >
+        <SendIcon className="w-4 h-4" />
+      </button>
+    </form>
+  );
+}
diff --git a/app/components/chatbot/ChatbotFlowCanvas.tsx b/app/components/chatbot/ChatbotFlowCanvas.tsx
index ed3f56f7..7bbbea55 100644
--- a/app/components/chatbot/ChatbotFlowCanvas.tsx
+++ b/app/components/chatbot/ChatbotFlowCanvas.tsx
@@ -31,7 +31,6 @@ interface ChatbotFlowCanvasProps {
   onNodesChange: (changes: NodeChange<ChatbotFlowNode>[]) => void;
   onEdgesChange: (changes: EdgeChange<Edge>[]) => void;
   onConnect: (connection: Connection) => void;
-  onSelectNode: (id: string) => void;
   updateNodeData: (id: string, patch: Partial<ChatbotNodeData>) => void;
 }
 
@@ -41,7 +40,6 @@ export default function ChatbotFlowCanvas({
   onNodesChange,
   onEdgesChange,
   onConnect,
-  onSelectNode,
   updateNodeData,
 }: ChatbotFlowCanvasProps) {
   const contextValue = useMemo(() => ({ updateNodeData }), [updateNodeData]);
@@ -56,7 +54,6 @@ export default function ChatbotFlowCanvas({
         onNodesChange={onNodesChange}
         onEdgesChange={onEdgesChange}
         onConnect={onConnect}
-        onNodeClick={(_, node) => onSelectNode(node.id)}
         fitView
         fitViewOptions={{ maxZoom: 1, padding: 0.2 }}
         proOptions={{ hideAttribution: true }}
diff --git a/app/components/chatbot/ChatbotMessageBubble.tsx b/app/components/chatbot/ChatbotMessageBubble.tsx
new file mode 100644
index 00000000..5f2717b7
--- /dev/null
+++ b/app/components/chatbot/ChatbotMessageBubble.tsx
@@ -0,0 +1,23 @@
+import { MarkdownContent } from "@/app/components/chat";
+import { ChatbotChatMessage } from "@/app/lib/types/chatbot";
+
+export default function ChatbotMessageBubble({
+  message,
+}: {
+  message: Pick<ChatbotChatMessage, "role" | "content">;
+}) {
+  const isUser = message.role === "user";
+  return (
+    <div className={`flex ${isUser ? "justify-end" : "justify-start"}`}>
+      <div
+        className={`max-w-[85%] rounded-2xl px-3 py-2 text-sm ${
+          isUser
+            ? "bg-accent-primary text-white whitespace-pre-wrap"
+            : "bg-bg-secondary text-text-primary"
+        }`}
+      >
+        {isUser ? message.content : <MarkdownContent text={message.content} />}
+      </div>
+    </div>
+  );
+}
diff --git a/app/components/chatbot/ChatbotSessionInfo.tsx b/app/components/chatbot/ChatbotSessionInfo.tsx
new file mode 100644
index 00000000..f2417c4c
--- /dev/null
+++ b/app/components/chatbot/ChatbotSessionInfo.tsx
@@ -0,0 +1,45 @@
+import {
+  ChatbotCompletionStatus,
+  ChatbotSessionStatus,
+} from "@/app/lib/types/chatbot";
+
+const NEUTRAL = "bg-bg-secondary text-text-secondary";
+const SUCCESS = "bg-status-success-bg text-status-success-text";
+const WARNING = "bg-status-warning-bg text-status-warning-text";
+
+function badgeFor(
+  status: ChatbotSessionStatus | null,
+  completionStatus: ChatbotCompletionStatus | null,
+): { label: string; className: string } | null {
+  if (!status) return null;
+  // Inactive = superseded by a newer session of the same chatbot.
+  if (status === "inactive") return { label: "Closed", className: NEUTRAL };
+  switch (completionStatus) {
+    case "complete":
+      return { label: "Complete", className: SUCCESS };
+    case "abandoned":
+      return { label: "Abandoned", className: NEUTRAL };
+    case "in_progress":
+      return { label: "In progress", className: WARNING };
+    default:
+      return { label: "Active", className: SUCCESS };
+  }
+}
+
+export function ChatbotStatusBadge({
+  status,
+  completionStatus,
+}: {
+  status: ChatbotSessionStatus | null;
+  completionStatus: ChatbotCompletionStatus | null;
+}) {
+  const badge = badgeFor(status, completionStatus);
+  if (!badge) return null;
+  return (
+    <span
+      className={`text-[11px] px-1.5 py-0.5 rounded font-medium shrink-0 ${badge.className}`}
+    >
+      {badge.label}
+    </span>
+  );
+}
diff --git a/app/components/chatbot/ChatbotTestPanel.tsx b/app/components/chatbot/ChatbotTestPanel.tsx
index 7884c61e..6161dff5 100644
--- a/app/components/chatbot/ChatbotTestPanel.tsx
+++ b/app/components/chatbot/ChatbotTestPanel.tsx
@@ -1,118 +1,137 @@
 /**
- * ChatbotTestPanel - Runs a throwaway test conversation against the selected
- * node's current (unsaved) prompt and config.
+ * ChatbotTestPanel - Chats with the saved flow's server-side session. Replies
+ * arrive asynchronously via the webhook stream, so the panel only renders
+ * state owned by useChatbotSession.
  */
 
 "use client";
 
-import { FormEvent, useEffect, useRef, useState } from "react";
+import { useEffect, useRef } from "react";
 import { Button } from "@/app/components/ui";
-import { MarkdownContent } from "@/app/components/chat";
-import { RefreshIcon, SendIcon } from "@/app/components/icons";
-import { useChatbotTest } from "@/app/hooks/useChatbotTest";
-import { ChatbotMessage, ChatbotNodeData } from "@/app/lib/types/chatbot";
+import { RefreshIcon } from "@/app/components/icons";
+import ChatbotMessageBubble from "@/app/components/chatbot/ChatbotMessageBubble";
+import ChatbotChatInput from "@/app/components/chatbot/ChatbotChatInput";
+import { ChatbotStatusBadge } from "@/app/components/chatbot/ChatbotSessionInfo";
+import {
+  ChatbotChatMessage,
+  ChatbotCompletionStatus,
+  ChatbotSessionStatus,
+} from "@/app/lib/types/chatbot";
 
 interface ChatbotTestPanelProps {
-  data: ChatbotNodeData;
+  hasSession: boolean;
+  sessionName: string | null;
+  status: ChatbotSessionStatus | null;
+  completionStatus: ChatbotCompletionStatus | null;
+  messages: ChatbotChatMessage[];
+  isPending: boolean;
+  isRestarting: boolean;
+  isDirty: boolean;
+  onSend: (message?: string) => Promise<boolean>;
+  onRestart: () => void;
 }
 
-function MessageBubble({ message }: { message: ChatbotMessage }) {
-  const isUser = message.role === "user";
-  return (
-    <div className={`flex ${isUser ? "justify-end" : "justify-start"}`}>
-      <div
-        className={`max-w-[85%] rounded-2xl px-3 py-2 text-sm ${
-          isUser
-            ? "bg-accent-primary text-white whitespace-pre-wrap"
-            : "bg-bg-secondary text-text-primary"
-        }`}
-      >
-        {isUser ? message.content : <MarkdownContent text={message.content} />}
-      </div>
-    </div>
-  );
+function inputPlaceholder(isEnded: boolean, hasStarted: boolean): string {
+  if (isEnded) return "Session closed";
+  if (!hasStarted) return "Click Start chat to begin…";
+  return "Reply as the user…";
 }
 
-export default function ChatbotTestPanel({ data }: ChatbotTestPanelProps) {
-  const { history, pendingMessage, isPending, canSend, send, reset } =
-    useChatbotTest(data);
-  const [input, setInput] = useState("");
+export default function ChatbotTestPanel({
+  hasSession,
+  sessionName,
+  status,
+  completionStatus,
+  messages,
+  isPending,
+  isRestarting,
+  isDirty,
+  onSend,
+  onRestart,
+}: ChatbotTestPanelProps) {
   const bottomRef = useRef<HTMLDivElement>(null);
-
-  const visible = history.filter((m) => m.role !== "system");
-  const hasStarted = history.length > 0;
+  // Inactive = superseded by a newer session; a complete one still chats.
+  const isEnded = status === "inactive";
+  const hasStarted = messages.length > 0;
 
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
-  }, [visible.length, pendingMessage, isPending]);
-
-  const handleSubmit = async (e: FormEvent) => {
-    e.preventDefault();
-    const text = input.trim();
-    if (!text || isPending) return;
-    setInput("");
-    const ok = await send(text);
-    if (!ok) setInput(text);
-  };
+  }, [messages.length, isPending]);
 
   return (
     <div className="flex flex-col flex-1 min-h-0">
+      <div className="px-4 py-3 border-b border-border flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2 min-w-0">
+          <p className="text-sm font-semibold text-text-primary truncate">
+            {sessionName ? `Test: ${sessionName}` : "Test chat"}
+          </p>
+          <ChatbotStatusBadge
+            status={status}
+            completionStatus={completionStatus}
+          />
+        </div>
+        {hasSession && (
+          <button
+            type="button"
+            onClick={onRestart}
+            disabled={isRestarting || isPending}
+            title="Start a new session with the saved flow"
+            className="p-1.5 rounded-full text-text-secondary hover:bg-neutral-100 hover:text-text-primary cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            <RefreshIcon className="w-4 h-4" />
+          </button>
+        )}
+      </div>
+
+      {isDirty && (
+        <p className="px-4 py-2 text-xs bg-status-warning-bg text-status-warning-text border-b border-border">
+          You have unsaved changes. The chat uses the last saved flow. Save to
+          test your edits.
+        </p>
+      )}
+
       <div className="flex-1 overflow-y-auto p-4 space-y-3">
-        {!hasStarted && !isPending && (
-          <div className="h-full flex flex-col items-center justify-center text-center gap-3">
-            <p className="text-sm text-text-secondary max-w-[260px]">
-              {canSend
-                ? "Start a test - the bot will send the first message."
-                : "Pick a configuration and write a system prompt to start testing."}
-            </p>
-            <Button size="sm" onClick={() => send()} disabled={!canSend}>
-              Start test
-            </Button>
-          </div>
+        {!hasSession ? (
+          <p className="h-full flex items-center justify-center text-center text-sm text-text-secondary px-6">
+            Pick a configuration, write a prompt and click Save to start a
+            chatbot session.
+          </p>
+        ) : (
+          messages.length === 0 &&
+          !isPending && (
+            <div className="h-full flex flex-col items-center justify-center text-center gap-3">
+              <p className="text-sm text-text-secondary max-w-[260px]">
+                The bot will send the first message.
+              </p>
+              <Button size="sm" onClick={() => onSend()}>
+                Start chat
+              </Button>
+            </div>
+          )
         )}
-        {visible.map((m, i) => (
-          <MessageBubble key={i} message={m} />
+        {messages.map((m) => (
+          <ChatbotMessageBubble key={m.id} message={m} />
         ))}
-        {pendingMessage && (
-          <MessageBubble message={{ role: "user", content: pendingMessage }} />
-        )}
         {isPending && (
           <p className="text-xs text-text-secondary animate-pulse">
             Bot is typing…
           </p>
         )}
+        {isEnded && (
+          <p className="text-xs text-center text-text-secondary">
+            This session was replaced by a newer one. Restart to continue
+            testing.
+          </p>
+        )}
         <div ref={bottomRef} />
       </div>
 
-      {hasStarted && (
-        <form
-          onSubmit={handleSubmit}
-          className="border-t border-border p-3 flex items-center gap-2"
-        >
-          <button
-            type="button"
-            onClick={reset}
-            title="Restart test"
-            className="p-2 rounded-full text-text-secondary hover:bg-neutral-100 hover:text-text-primary cursor-pointer"
-          >
-            <RefreshIcon className="w-4 h-4" />
-          </button>
-          <input
-            value={input}
-            onChange={(e) => setInput(e.target.value)}
-            placeholder="Reply as the user…"
-            disabled={isPending}
-            className="flex-1 px-3 py-2 rounded-full border border-border text-sm bg-bg-primary text-text-primary focus:outline-none focus:border-accent-primary disabled:opacity-60"
-          />
-          <button
-            type="submit"
-            disabled={isPending || !input.trim()}
-            title="Send"
-            className="p-2 rounded-full bg-accent-primary text-white hover:bg-accent-hover disabled:bg-neutral-200 disabled:text-text-secondary cursor-pointer disabled:cursor-not-allowed"
-          >
-            <SendIcon className="w-4 h-4" />
-          </button>
-        </form>
+      {hasSession && (
+        <ChatbotChatInput
+          disabled={isPending || isEnded || !hasStarted}
+          placeholder={inputPlaceholder(isEnded, hasStarted)}
+          onSend={onSend}
+        />
       )}
     </div>
   );
diff --git a/app/components/chatbot/LlmNode.tsx b/app/components/chatbot/LlmNode.tsx
index 71c9c002..14d03202 100644
--- a/app/components/chatbot/LlmNode.tsx
+++ b/app/components/chatbot/LlmNode.tsx
@@ -1,18 +1,19 @@
 /**
- * LlmNode - Editable LLM step on the chatbot canvas: config, prompt and limits
- * are edited inline, mirroring the node's data used by the test panel.
+ * LlmNode - Editable LLM step on the chatbot canvas: config and prompt are
+ * edited inline; Save turns them into a chatbot session.
  */
 
 "use client";
 
 import { Handle, NodeProps, Position } from "@xyflow/react";
 import { ChatConfigPicker } from "@/app/components/chat";
+import { CHATBOT_NAME_MAX_LENGTH } from "@/app/lib/constants";
+import { useChatbotStore } from "@/app/lib/store/chatbot";
 import { ChatbotLlmNode, ChatbotNodeData } from "@/app/lib/types/chatbot";
 import { useChatbotFlowContext } from "@/app/components/chatbot/ChatbotFlowContext";
 import { FLOW_HANDLE_STYLE } from "@/app/components/chatbot/flowHandleStyle";
 import NodeFieldLabel from "@/app/components/chatbot/NodeFieldLabel";
 import LlmNodePromptField from "@/app/components/chatbot/LlmNodePromptField";
-import LlmNodeAdvanced from "@/app/components/chatbot/LlmNodeAdvanced";
 
 const PORT_LABEL_CLASS = "text-sm font-semibold font-mono text-text-primary";
 
@@ -22,6 +23,8 @@ export default function LlmNode({
   selected,
 }: NodeProps<ChatbotLlmNode>) {
   const { updateNodeData } = useChatbotFlowContext();
+  // Shown only once the backend has generated it on the first save.
+  const chatbotRef = useChatbotStore((s) => s.chatbotRef);
   const update = (patch: Partial<ChatbotNodeData>) => updateNodeData(id, patch);
 
   return (
@@ -36,10 +39,15 @@ export default function LlmNode({
         <input
           value={data.label}
           onChange={(e) => update({ label: e.target.value })}
+          maxLength={CHATBOT_NAME_MAX_LENGTH}
           placeholder="Untitled step"
           className="nodrag w-full px-6 text-center text-base font-semibold text-text-primary bg-transparent focus:outline-none"
         />
-        <p className="text-[11px] text-text-secondary truncate">{id}</p>
+        {chatbotRef && (
+          <p className="text-[11px] text-text-secondary truncate">
+            {chatbotRef}
+          </p>
+        )}
       </div>
 
       <div className="relative px-4 py-1">
@@ -71,8 +79,6 @@ export default function LlmNode({
           value={data.systemPrompt}
           onChange={(systemPrompt) => update({ systemPrompt })}
         />
-
-        <LlmNodeAdvanced data={data} onChange={update} />
       </div>
 
       <div className="relative px-4 py-2.5 border-t-2 border-text-primary text-right">
diff --git a/app/components/chatbot/LlmNodeAdvanced.tsx b/app/components/chatbot/LlmNodeAdvanced.tsx
deleted file mode 100644
index 726f43c9..00000000
--- a/app/components/chatbot/LlmNodeAdvanced.tsx
+++ /dev/null
@@ -1,63 +0,0 @@
-/**
- * LlmNodeAdvanced - Collapsible per-request limits for an LLM node.
- */
-
-"use client";
-
-import { useState } from "react";
-import { Field } from "@/app/components/ui";
-import { ChevronDownIcon, ChevronUpIcon } from "@/app/components/icons";
-import { ChatbotNodeData } from "@/app/lib/types/chatbot";
-
-interface LlmNodeAdvancedProps {
-  data: ChatbotNodeData;
-  onChange: (patch: Partial<ChatbotNodeData>) => void;
-}
-
-function toPositiveInt(value: string, fallback: number): number {
-  const n = Number.parseInt(value, 10);
-  return Number.isFinite(n) && n > 0 ? n : fallback;
-}
-
-export default function LlmNodeAdvanced({
-  data,
-  onChange,
-}: LlmNodeAdvancedProps) {
-  const [open, setOpen] = useState(false);
-  const Chevron = open ? ChevronUpIcon : ChevronDownIcon;
-
-  return (
-    <div>
-      <button
-        type="button"
-        onClick={() => setOpen((prev) => !prev)}
-        className="nodrag w-full flex items-center justify-center gap-1 py-1 text-xs font-semibold text-text-primary hover:text-accent-primary cursor-pointer"
-      >
-        Advanced
-        <Chevron className="w-3 h-3" />
-      </button>
-      {open && (
-        <div className="nodrag grid grid-cols-2 gap-2 pt-2">
-          <Field
-            label="Max tokens"
-            type="number"
-            value={String(data.maxTokens)}
-            onChange={(v) =>
-              onChange({ maxTokens: toPositiveInt(v, data.maxTokens) })
-            }
-          />
-          <Field
-            label="History token limit"
-            type="number"
-            value={String(data.historyTokenLimit)}
-            onChange={(v) =>
-              onChange({
-                historyTokenLimit: toPositiveInt(v, data.historyTokenLimit),
-              })
-            }
-          />
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/app/hooks/useChatbotFlow.ts b/app/hooks/useChatbotFlow.ts
index de75ff36..55adacfb 100644
--- a/app/hooks/useChatbotFlow.ts
+++ b/app/hooks/useChatbotFlow.ts
@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
   addEdge,
   Connection,
@@ -8,10 +8,8 @@ import {
   useEdgesState,
   useNodesState,
 } from "@xyflow/react";
-import {
-  CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT,
-  CHATBOT_DEFAULT_MAX_TOKENS,
-} from "@/app/lib/constants";
+import { DEFAULT_CHATBOT_NAME } from "@/app/lib/constants";
+import { useChatbotStore } from "@/app/lib/store/chatbot";
 import {
   ChatbotFlowNode,
   ChatbotLlmNode,
@@ -20,35 +18,17 @@ import {
 
 const INPUT_ID = "input";
 const OUTPUT_ID = "output";
-const LLM_ID_PREFIX = "LLMResponseWithPrompt";
-const INITIAL_LLM_ID = `${LLM_ID_PREFIX}-1`;
-
-function shortId(): string {
-  return Math.random().toString(16).slice(2, 7);
-}
+// Fixed so server and client render the same id (avoids hydration mismatch).
+const LLM_ID = "LLMResponseWithPrompt-1";
 
-function createLlmNode(
-  position: { x: number; y: number },
-  label = "New step",
-  id = `${LLM_ID_PREFIX}-${shortId()}`,
-): ChatbotLlmNode {
-  return {
-    id,
-    type: "llm",
-    position,
-    data: {
-      label,
-      systemPrompt: "",
-      configId: "",
-      configVersion: undefined,
-      maxTokens: CHATBOT_DEFAULT_MAX_TOKENS,
-      historyTokenLimit: CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT,
-    },
-  };
-}
+const DEFAULT_NODE_DATA: ChatbotNodeData = {
+  label: DEFAULT_CHATBOT_NAME,
+  systemPrompt: "",
+  configId: "",
+  configVersion: undefined,
+};
 
 function createInitialFlow(): { nodes: ChatbotFlowNode[]; edges: Edge[] } {
-  const llm = createLlmNode({ x: 260, y: 0 }, "Onboarding", INITIAL_LLM_ID);
   return {
     nodes: [
       {
@@ -58,18 +38,24 @@ function createInitialFlow(): { nodes: ChatbotFlowNode[]; edges: Edge[] } {
         data: { label: "Input" },
         deletable: false,
       },
-      llm,
+      {
+        id: LLM_ID,
+        type: "llm",
+        position: { x: 260, y: 0 },
+        data: DEFAULT_NODE_DATA,
+        deletable: false,
+      },
       {
         id: OUTPUT_ID,
         type: "flowOutput",
-        position: { x: 640, y: 270 },
+        position: { x: 640, y: 230 },
         data: { label: "Output" },
         deletable: false,
       },
     ],
     edges: [
-      { id: `${INPUT_ID}->${llm.id}`, source: INPUT_ID, target: llm.id },
-      { id: `${llm.id}->${OUTPUT_ID}`, source: llm.id, target: OUTPUT_ID },
+      { id: `${INPUT_ID}->${LLM_ID}`, source: INPUT_ID, target: LLM_ID },
+      { id: `${LLM_ID}->${OUTPUT_ID}`, source: LLM_ID, target: OUTPUT_ID },
     ],
   };
 }
@@ -78,31 +64,56 @@ function isLlmNode(node: ChatbotFlowNode): node is ChatbotLlmNode {
   return node.type === "llm";
 }
 
-/** Owns the in-memory (unsaved) chatbot flow graph and the node under test. */
+function isSameData(a: ChatbotNodeData, b: ChatbotNodeData): boolean {
+  return (
+    a.label === b.label &&
+    a.systemPrompt === b.systemPrompt &&
+    a.configId === b.configId &&
+    (a.configVersion ?? null) === (b.configVersion ?? null)
+  );
+}
+
+/**
+ * Owns the canvas graph (Input → LLM → Output) and tracks the LLM node's
+ * edits against the last saved version, for the Save / Discard buttons.
+ */
 export function useChatbotFlow() {
   const [initial] = useState(createInitialFlow);
   const [nodes, setNodes, onNodesChange] = useNodesState<ChatbotFlowNode>(
     initial.nodes,
   );
   const [edges, setEdges, onEdgesChange] = useEdgesState<Edge>(initial.edges);
-  const [selectedId, setSelectedId] = useState<string | null>(null);
 
-  const llmNodes = nodes.filter(isLlmNode);
-  // Fall back to the first LLM node so the test panel always has a target.
-  const selectedNode =
-    llmNodes.find((n) => n.id === selectedId) ?? llmNodes[0] ?? null;
+  const savedFlow = useChatbotStore((s) => s.savedFlow);
+  const hasHydrated = useChatbotStore((s) => s.hasHydrated);
+  const setSavedFlow = useChatbotStore((s) => s.setSavedFlow);
+
+  const llmNode = nodes.find(isLlmNode) ?? null;
+  const baseline = savedFlow ?? DEFAULT_NODE_DATA;
+  const isDirty = !!llmNode && !isSameData(llmNode.data, baseline);
+
+  const replaceNodeData = useCallback(
+    (data: ChatbotNodeData) => {
+      setNodes((prev) =>
+        prev.map((n) => (isLlmNode(n) ? { ...n, data: { ...data } } : n)),
+      );
+    },
+    [setNodes],
+  );
+
+  // Load the saved flow into the node once localStorage has rehydrated.
+  const restoredRef = useRef(false);
+  useEffect(() => {
+    if (!hasHydrated || restoredRef.current) return;
+    restoredRef.current = true;
+    if (savedFlow) replaceNodeData(savedFlow);
+  }, [hasHydrated, savedFlow, replaceNodeData]);
 
   const onConnect = useCallback(
     (connection: Connection) => setEdges((eds) => addEdge(connection, eds)),
     [setEdges],
   );
 
-  const addNode = useCallback(() => {
-    const node = createLlmNode({ x: 260, y: 160 + llmNodes.length * 60 });
-    setNodes((prev) => [...prev, node]);
-    setSelectedId(node.id);
-  }, [llmNodes.length, setNodes]);
-
   const updateNodeData = useCallback(
     (id: string, patch: Partial<ChatbotNodeData>) => {
       setNodes((prev) =>
@@ -116,15 +127,26 @@ export function useChatbotFlow() {
     [setNodes],
   );
 
+  const discard = useCallback(
+    () => replaceNodeData(baseline),
+    [baseline, replaceNodeData],
+  );
+
+  const markSaved = useCallback(
+    (data: ChatbotNodeData) => setSavedFlow({ ...data }),
+    [setSavedFlow],
+  );
+
   return {
     nodes,
     edges,
     onNodesChange,
     onEdgesChange,
     onConnect,
-    selectedNode,
-    setSelectedId,
-    addNode,
     updateNodeData,
+    llmNode,
+    isDirty,
+    discard,
+    markSaved,
   };
 }
diff --git a/app/hooks/useChatbotPendingReply.ts b/app/hooks/useChatbotPendingReply.ts
new file mode 100644
index 00000000..fba4fdf3
--- /dev/null
+++ b/app/hooks/useChatbotPendingReply.ts
@@ -0,0 +1,39 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Tracks "waiting for the bot's reply" for webhook-delivered turns, giving up
+ * after `timeoutMs` so the UI never spins forever.
+ */
+export function useChatbotPendingReply(
+  timeoutMs: number,
+  onTimeout: () => void,
+) {
+  const [isPending, setIsPending] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onTimeoutRef = useRef(onTimeout);
+  useEffect(() => {
+    onTimeoutRef.current = onTimeout;
+  });
+
+  const clear = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = null;
+    setIsPending(false);
+  }, []);
+
+  const start = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    setIsPending(true);
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      setIsPending(false);
+      onTimeoutRef.current();
+    }, timeoutMs);
+  }, [timeoutMs]);
+
+  useEffect(() => clear, [clear]);
+
+  return { isPending, start, clear };
+}
diff --git a/app/hooks/useChatbotReplyStream.ts b/app/hooks/useChatbotReplyStream.ts
new file mode 100644
index 00000000..641c80d2
--- /dev/null
+++ b/app/hooks/useChatbotReplyStream.ts
@@ -0,0 +1,43 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { ChatbotSessionEvent } from "@/app/lib/types/chatbot";
+
+/**
+ * Keeps an SSE connection to the webhook stream for one chatbot session and
+ * calls `onEvent` for every reply Kaapi delivers. EventSource reconnects on
+ * its own and resumes via `Last-Event-ID`; `getAfterSeq` skips replies the
+ * page already applied before a reload.
+ */
+export function useChatbotReplyStream(
+  sessionId: string | null,
+  getAfterSeq: () => number,
+  onEvent: (event: ChatbotSessionEvent) => void,
+) {
+  // Latest callbacks without reopening the stream on every render.
+  const onEventRef = useRef(onEvent);
+  const getAfterSeqRef = useRef(getAfterSeq);
+  useEffect(() => {
+    onEventRef.current = onEvent;
+    getAfterSeqRef.current = getAfterSeq;
+  });
+
+  useEffect(() => {
+    if (!sessionId || typeof EventSource === "undefined") return;
+    const params = new URLSearchParams({
+      session_id: sessionId,
+      after: String(getAfterSeqRef.current()),
+    });
+    const source = new EventSource(`/api/webhooks/chatbot/stream?${params}`);
+    source.addEventListener("reply", (e) => {
+      try {
+        onEventRef.current(
+          JSON.parse((e as MessageEvent).data) as ChatbotSessionEvent,
+        );
+      } catch (err) {
+        console.error("chatbot SSE parse error:", err);
+      }
+    });
+    return () => source.close();
+  }, [sessionId]);
+}
diff --git a/app/hooks/useChatbotSession.ts b/app/hooks/useChatbotSession.ts
new file mode 100644
index 00000000..dacae371
--- /dev/null
+++ b/app/hooks/useChatbotSession.ts
@@ -0,0 +1,228 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { useAuth } from "@/app/lib/context/AuthContext";
+import { useToast } from "@/app/hooks/useToast";
+import { useChatbotReplyStream } from "@/app/hooks/useChatbotReplyStream";
+import { useChatbotPendingReply } from "@/app/hooks/useChatbotPendingReply";
+import { useChatbotStore } from "@/app/lib/store/chatbot";
+import {
+  CHATBOT_REPLY_TIMEOUT_MS,
+  DEFAULT_CHATBOT_NAME,
+} from "@/app/lib/constants";
+import {
+  createChatbotSession,
+  getLatestChatbotSession,
+  sendChatbotSessionMessage,
+} from "@/app/lib/chatbotClient";
+import {
+  readChatbotSessionCookie,
+  writeChatbotSessionCookie,
+} from "@/app/lib/utils/chatbotSessionCookie";
+import {
+  ChatbotNodeData,
+  ChatbotSessionEvent,
+  ChatbotCompletionStatus,
+  ChatbotSessionStatus,
+} from "@/app/lib/types/chatbot";
+
+/**
+ * Owns the server-side chatbot session used by the test panel: creating it
+ * on Save (id kept in a cookie), sending turns, and applying replies that
+ * arrive asynchronously through the webhook stream.
+ */
+export function useChatbotSession() {
+  const { activeKey, currentUser, isAuthenticated } = useAuth();
+  const apiKey = activeKey?.key ?? "";
+  const toast = useToast();
+
+  const hasHydrated = useChatbotStore((s) => s.hasHydrated);
+  const messages = useChatbotStore((s) => s.messages);
+  const bindSession = useChatbotStore((s) => s.bindSession);
+  const appendMessage = useChatbotStore((s) => s.appendMessage);
+  const removeMessage = useChatbotStore((s) => s.removeMessage);
+  const setLastEventSeq = useChatbotStore((s) => s.setLastEventSeq);
+  const chatbotRef = useChatbotStore((s) => s.chatbotRef);
+  const setChatbotRef = useChatbotStore((s) => s.setChatbotRef);
+
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const [sessionName, setSessionName] = useState<string | null>(null);
+  const [status, setStatus] = useState<ChatbotSessionStatus | null>(null);
+  const [completionStatus, setCompletionStatus] =
+    useState<ChatbotCompletionStatus | null>(null);
+  const [isCreating, setIsCreating] = useState(false);
+  const pending = useChatbotPendingReply(CHATBOT_REPLY_TIMEOUT_MS, () =>
+    toast.error("No reply from the chatbot yet. Try sending again."),
+  );
+  const { clear: clearPending, start: startPending } = pending;
+
+  const userRef = currentUser?.id ?? activeKey?.id;
+  const contactRef = userRef ? `kaapi-user-${userRef}` : null;
+
+  const adoptSession = useCallback(
+    (id: string) => {
+      setSessionId(id);
+      bindSession(id);
+    },
+    [bindSession],
+  );
+
+  // Restore the session from the cookie, falling back to this chatbot's
+  // latest session for the contact; either way refresh its status. The
+  // lookup needs the chatbot ref, which only exists after the first save.
+  useEffect(() => {
+    if (!hasHydrated || !isAuthenticated || !contactRef) return;
+    const cookieId = readChatbotSessionCookie();
+    if (cookieId) adoptSession(cookieId);
+    if (!chatbotRef) return;
+
+    let cancelled = false;
+    getLatestChatbotSession(contactRef, chatbotRef, apiKey).then((summary) => {
+      if (cancelled || !summary) return;
+      if (!cookieId) {
+        writeChatbotSessionCookie(summary.session_id);
+        adoptSession(summary.session_id);
+      }
+      if (!cookieId || cookieId === summary.session_id) {
+        setSessionName(summary.name || DEFAULT_CHATBOT_NAME);
+        setStatus(summary.status);
+        setCompletionStatus(summary.completion_status);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    hasHydrated,
+    isAuthenticated,
+    contactRef,
+    chatbotRef,
+    apiKey,
+    adoptSession,
+  ]);
+
+  const handleEvent = useCallback(
+    (event: ChatbotSessionEvent) => {
+      if (event.seq <= useChatbotStore.getState().lastEventSeq) return;
+      setLastEventSeq(event.seq);
+      clearPending();
+      if (!event.success) {
+        toast.error(event.error || "The chatbot couldn't reply.");
+        return;
+      }
+      if (event.reply) {
+        appendMessage({
+          id: crypto.randomUUID(),
+          role: "assistant",
+          content: event.reply,
+        });
+      }
+      if (event.status) setStatus(event.status);
+      if (event.completionStatus) setCompletionStatus(event.completionStatus);
+    },
+    [appendMessage, clearPending, setLastEventSeq, toast],
+  );
+
+  useChatbotReplyStream(
+    hasHydrated ? sessionId : null,
+    () => useChatbotStore.getState().lastEventSeq,
+    handleEvent,
+  );
+
+  /** Creates a new session for the saved flow and makes it the active one. */
+  const startSession = useCallback(
+    async (data: ChatbotNodeData): Promise<boolean> => {
+      if (!contactRef) {
+        toast.error("Couldn't identify your account. Please log in again.");
+        return false;
+      }
+      const name = data.label.trim() || DEFAULT_CHATBOT_NAME;
+      setIsCreating(true);
+      try {
+        const created = await createChatbotSession(
+          {
+            name,
+            chatbot_ref: chatbotRef ?? undefined,
+            config_id: data.configId,
+            config_version: data.configVersion,
+            contact_ref: contactRef,
+            system_prompt: data.systemPrompt,
+          },
+          apiKey,
+        );
+        writeChatbotSessionCookie(created.sessionId);
+        setChatbotRef(created.chatbotRef);
+        clearPending();
+        adoptSession(created.sessionId);
+        setSessionName(name);
+        setStatus("active");
+        setCompletionStatus("in_progress");
+        return true;
+      } catch (err) {
+        toast.error(
+          err instanceof Error ? err.message : "Failed to save the flow.",
+        );
+        return false;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [
+      adoptSession,
+      apiKey,
+      chatbotRef,
+      clearPending,
+      contactRef,
+      setChatbotRef,
+      toast,
+    ],
+  );
+
+  /** Queues a turn; omit `message` to get the greeting on a fresh session. */
+  const send = useCallback(
+    async (message?: string): Promise<boolean> => {
+      if (!sessionId) {
+        toast.error("Save the flow first to start a session.");
+        return false;
+      }
+      const optimisticId = message ? crypto.randomUUID() : null;
+      if (optimisticId && message) {
+        appendMessage({ id: optimisticId, role: "user", content: message });
+      }
+      startPending();
+
+      try {
+        await sendChatbotSessionMessage(sessionId, message, apiKey);
+        return true;
+      } catch (err) {
+        if (optimisticId) removeMessage(optimisticId);
+        clearPending();
+        toast.error(
+          err instanceof Error ? err.message : "Failed to send the message.",
+        );
+        return false;
+      }
+    },
+    [
+      appendMessage,
+      apiKey,
+      clearPending,
+      removeMessage,
+      sessionId,
+      startPending,
+      toast,
+    ],
+  );
+
+  return {
+    sessionId,
+    sessionName,
+    status,
+    completionStatus,
+    messages: sessionId ? messages : [],
+    isPending: pending.isPending,
+    isCreating,
+    startSession,
+    send,
+  };
+}
diff --git a/app/hooks/useChatbotTest.ts b/app/hooks/useChatbotTest.ts
deleted file mode 100644
index 5988fbb1..00000000
--- a/app/hooks/useChatbotTest.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useAuth } from "@/app/lib/context/AuthContext";
-import { useToast } from "@/app/hooks/useToast";
-import { sendChatbotMessage } from "@/app/lib/chatbotClient";
-import { ChatbotMessage, ChatbotNodeData } from "@/app/lib/types/chatbot";
-
-/**
- * Drives the chatbot test panel for a single flow node. History lives only in
- * React state; it is cleared whenever the node's prompt or config changes so
- * every edit starts a fresh test.
- */
-export function useChatbotTest(data: ChatbotNodeData) {
-  const { activeKey } = useAuth();
-  const apiKey = activeKey?.key ?? "";
-  const toast = useToast();
-
-  const [history, setHistory] = useState<ChatbotMessage[]>([]);
-  const [pendingMessage, setPendingMessage] = useState<string | null>(null);
-  const [isPending, setIsPending] = useState(false);
-
-  const resetKey = `${data.systemPrompt}\u0000${data.configId}\u0000${data.configVersion ?? ""}`;
-  const [prevResetKey, setPrevResetKey] = useState(resetKey);
-  if (prevResetKey !== resetKey) {
-    setPrevResetKey(resetKey);
-    setHistory([]);
-    setPendingMessage(null);
-    setIsPending(false);
-  }
-
-  // Bumped on every reset so responses from an outdated test are dropped.
-  const generationRef = useRef(0);
-  useEffect(() => {
-    generationRef.current += 1;
-  }, [resetKey]);
-
-  const canSend = !!data.configId && !!data.systemPrompt.trim();
-
-  const send = useCallback(
-    async (message?: string): Promise<boolean> => {
-      if (!data.configId) {
-        toast.error("Select a configuration and version first.");
-        return false;
-      }
-      if (!data.systemPrompt.trim()) {
-        toast.error("Add a system prompt to the node first.");
-        return false;
-      }
-
-      const generation = generationRef.current;
-      setIsPending(true);
-      setPendingMessage(message ?? null);
-      try {
-        const messages = await sendChatbotMessage(
-          {
-            config_id: data.configId,
-            config_version: data.configVersion,
-            system_prompt: data.systemPrompt,
-            history,
-            message,
-            max_tokens: data.maxTokens,
-            history_token_limit: data.historyTokenLimit,
-          },
-          apiKey,
-        );
-        if (generation !== generationRef.current) return false;
-        setHistory(messages);
-        return true;
-      } catch (err) {
-        if (generation !== generationRef.current) return false;
-        toast.error(
-          err instanceof Error ? err.message : "Something went wrong",
-        );
-        return false;
-      } finally {
-        if (generation === generationRef.current) {
-          setIsPending(false);
-          setPendingMessage(null);
-        }
-      }
-    },
-    [apiKey, data, history, toast],
-  );
-
-  const reset = useCallback(() => {
-    generationRef.current += 1;
-    setHistory([]);
-    setPendingMessage(null);
-    setIsPending(false);
-  }, []);
-
-  return { history, pendingMessage, isPending, canSend, send, reset };
-}
diff --git a/app/hooks/useConfigs.ts b/app/hooks/useConfigs.ts
index 0e830699..e12f867f 100644
--- a/app/hooks/useConfigs.ts
+++ b/app/hooks/useConfigs.ts
@@ -268,7 +268,7 @@ export function useConfigs(options?: { pageSize?: number }): UseConfigsResult {
         console.error(`Failed to load version list for config ${config_id}`);
       }
     },
-    [apiKey],
+    [apiKey, isAuthenticated],
   );
 
   /**
@@ -354,7 +354,7 @@ export function useConfigs(options?: { pageSize?: number }): UseConfigsResult {
       pendingSingleVersionLoads.set(key, loadPromise);
       return loadPromise;
     },
-    [configs],
+    [configs, apiKey, isAuthenticated],
   );
 
   /**
@@ -426,7 +426,7 @@ export function useConfigs(options?: { pageSize?: number }): UseConfigsResult {
       console.error("Failed to load more configs");
       setIsLoadingMore(false);
     }
-  }, [configs, pageSize]);
+  }, [configs, pageSize, activeKey, isAuthenticated]);
 
   useEffect(() => {
     fetchConfigs();
diff --git a/app/lib/chatbotClient.ts b/app/lib/chatbotClient.ts
index d7ece704..ac837ef6 100644
--- a/app/lib/chatbotClient.ts
+++ b/app/lib/chatbotClient.ts
@@ -1,26 +1,71 @@
 import { apiFetch } from "@/app/lib/apiClient";
 import {
-  ChatbotMessage,
-  ChatbotMessageRequest,
-  ChatbotMessageResponse,
+  ChatbotSessionSummary,
+  ChatbotSessionSummaryResponse,
+  CreateChatbotSessionRequest,
+  CreateChatbotSessionResponse,
+  SendChatbotSessionMessageResponse,
 } from "@/app/lib/types/chatbot";
 
 /**
- * Sends one turn of a chatbot test conversation. The backend is stateless:
- * it takes the full history and returns the updated history (old messages
- * plus the new user/assistant turn).
+ * Stores the prompt + config pin server-side. Returns the new session id and
+ * the chatbot ref (generated by the backend on a chatbot's first session).
  */
-export async function sendChatbotMessage(
-  body: ChatbotMessageRequest,
+export async function createChatbotSession(
+  body: CreateChatbotSessionRequest,
   apiKey: string,
-): Promise<ChatbotMessage[]> {
-  const res = await apiFetch<ChatbotMessageResponse>(
-    "/api/chatbot/message",
+): Promise<{ sessionId: string; chatbotRef: string }> {
+  const res = await apiFetch<CreateChatbotSessionResponse>(
+    "/api/chatbot/sessions",
     apiKey,
     { method: "POST", body: JSON.stringify(body) },
   );
-  if (!res.success || !res.data?.messages) {
-    throw new Error(res.error || "Failed to get a response from the chatbot.");
+  if (!res.success || !res.data?.session_id) {
+    throw new Error(res.error || "Failed to create the chatbot session.");
+  }
+  return {
+    sessionId: res.data.session_id,
+    chatbotRef: res.data.chatbot_ref,
+  };
+}
+
+/** Latest session of this chatbot for the contact, or null when there is none. */
+export async function getLatestChatbotSession(
+  contactRef: string,
+  chatbotRef: string,
+  apiKey: string,
+): Promise<ChatbotSessionSummary | null> {
+  try {
+    const params = new URLSearchParams({
+      contact_ref: contactRef,
+      chatbot_ref: chatbotRef,
+    });
+    const res = await apiFetch<ChatbotSessionSummaryResponse>(
+      `/api/chatbot/sessions?${params}`,
+      apiKey,
+    );
+    return res.success ? (res.data ?? null) : null;
+  } catch {
+    // 404 = no session for this contact yet.
+    return null;
+  }
+}
+
+/**
+ * Queues one turn; the reply arrives later through the webhook stream.
+ * Omit `message` on a fresh session to get the bot's greeting.
+ */
+export async function sendChatbotSessionMessage(
+  sessionId: string,
+  message: string | undefined,
+  apiKey: string,
+): Promise<void> {
+  const res = await apiFetch<SendChatbotSessionMessageResponse>(
+    `/api/chatbot/sessions/${encodeURIComponent(sessionId)}/message`,
+    apiKey,
+    { method: "POST", body: JSON.stringify(message ? { message } : {}) },
+  );
+  if (!res.success) {
+    throw new Error(res.error || "Failed to send the message.");
   }
-  return res.data.messages;
 }
diff --git a/app/lib/constants.ts b/app/lib/constants.ts
index 0a32cebd..45d0d926 100644
--- a/app/lib/constants.ts
+++ b/app/lib/constants.ts
@@ -22,6 +22,7 @@ export const STORAGE_KEYS = {
   DOCUMENT_SIZES: "document_file_sizes",
   SIDEBAR_MENUS: "sidebar-expanded-menus",
   CHAT_STATE: "kaapi_chat_state",
+  CHATBOT_STATE: "kaapi_chatbot_state",
 } as const;
 
 export const COOKIE_KEYS = {
@@ -29,6 +30,7 @@ export const COOKIE_KEYS = {
   FEATURES: "kaapi_features",
   API_KEY: "kaapi_api_key",
   API_KEY_META: "kaapi_api_key_meta",
+  CHATBOT_SESSION: "kaapi_chatbot_session",
 } as const;
 
 export const AUTH_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
@@ -214,6 +216,9 @@ export const PAGER_BUTTON_IDLE =
 export const PAGER_BUTTON_CURRENT =
   "border-accent-primary bg-accent-primary text-white font-semibold";
 
-/** Chatbot flow — default per-request limits for the test panel. */
-export const CHATBOT_DEFAULT_MAX_TOKENS = 2048;
-export const CHATBOT_DEFAULT_HISTORY_TOKEN_LIMIT = 6000;
+/** Chatbot flow — how long the test panel waits for a webhook reply. */
+export const CHATBOT_REPLY_TIMEOUT_MS = 90_000;
+/** Backend limit on a chatbot session's `name`. */
+export const CHATBOT_NAME_MAX_LENGTH = 255;
+/** Name used when the title is empty or the backend returns none (matches backend default). */
+export const DEFAULT_CHATBOT_NAME = "Untitled Chatbot";
diff --git a/app/lib/store/chatbot.ts b/app/lib/store/chatbot.ts
new file mode 100644
index 00000000..b63ab3d1
--- /dev/null
+++ b/app/lib/store/chatbot.ts
@@ -0,0 +1,91 @@
+"use client";
+
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+
+import { STORAGE_KEYS } from "@/app/lib/constants";
+import { ChatbotChatMessage, ChatbotNodeData } from "@/app/lib/types/chatbot";
+
+const MAX_PERSISTED_MESSAGES = 100;
+
+interface ChatbotState {
+  /** Last saved node data; the baseline for Discard and dirty checks. */
+  savedFlow: ChatbotNodeData | null;
+  /** Backend-generated chatbot id; null until the first save. */
+  chatbotRef: string | null;
+  /** Session the stored transcript belongs to (the cookie holds the active id). */
+  messagesSessionId: string | null;
+  messages: ChatbotChatMessage[];
+  /** Last webhook event applied, so reconnects don't replay it. */
+  lastEventSeq: number;
+  hasHydrated: boolean;
+}
+
+interface ChatbotActions {
+  setSavedFlow: (flow: ChatbotNodeData) => void;
+  setChatbotRef: (ref: string) => void;
+  /** Points the transcript at a session, clearing it if the session changed. */
+  bindSession: (sessionId: string) => void;
+  appendMessage: (message: ChatbotChatMessage) => void;
+  removeMessage: (id: string) => void;
+  setLastEventSeq: (seq: number) => void;
+  setHasHydrated: (value: boolean) => void;
+}
+
+const INITIAL_STATE: ChatbotState = {
+  savedFlow: null,
+  chatbotRef: null,
+  messagesSessionId: null,
+  messages: [],
+  lastEventSeq: 0,
+  hasHydrated: false,
+};
+
+export const useChatbotStore = create<ChatbotState & ChatbotActions>()(
+  persist(
+    (set) => ({
+      ...INITIAL_STATE,
+
+      setSavedFlow: (flow) => set({ savedFlow: flow }),
+
+      setChatbotRef: (ref) => set({ chatbotRef: ref }),
+
+      bindSession: (sessionId) =>
+        set((state) =>
+          state.messagesSessionId === sessionId
+            ? state
+            : { messagesSessionId: sessionId, messages: [], lastEventSeq: 0 },
+        ),
+
+      appendMessage: (message) =>
+        set((state) => ({
+          messages: [...state.messages, message].slice(-MAX_PERSISTED_MESSAGES),
+        })),
+
+      removeMessage: (id) =>
+        set((state) => ({
+          messages: state.messages.filter((m) => m.id !== id),
+        })),
+
+      setLastEventSeq: (seq) => set({ lastEventSeq: seq }),
+
+      setHasHydrated: (value) => set({ hasHydrated: value }),
+    }),
+    {
+      name: STORAGE_KEYS.CHATBOT_STATE,
+      version: 1,
+      storage: createJSONStorage(() => localStorage),
+      skipHydration: true,
+      partialize: (state) => ({
+        savedFlow: state.savedFlow,
+        chatbotRef: state.chatbotRef,
+        messagesSessionId: state.messagesSessionId,
+        messages: state.messages,
+        lastEventSeq: state.lastEventSeq,
+      }),
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true);
+      },
+    },
+  ),
+);
diff --git a/app/lib/store/chatbotSessionStore.ts b/app/lib/store/chatbotSessionStore.ts
new file mode 100644
index 00000000..cbfcfa22
--- /dev/null
+++ b/app/lib/store/chatbotSessionStore.ts
@@ -0,0 +1,97 @@
+/**
+ * Server-side in-memory store for chatbot session replies. The backend POSTs
+ * each completed turn to `/api/webhooks/chatbot`; this store keeps a short
+ * per-session buffer and fans events out to open SSE streams, so the browser
+ * never has to receive webhooks directly.
+ */
+
+import type {
+  ChatbotSessionEvent,
+  ChatbotSessionEventListener,
+  ChatbotSessionStoreShape,
+} from "@/app/lib/types/chatbot";
+
+const globalKey = Symbol.for("kaapi.chatbotSessionStore");
+
+type WithStore = { [globalKey]?: ChatbotSessionStoreShape };
+const g = globalThis as unknown as WithStore;
+
+if (!g[globalKey]) {
+  g[globalKey] = { events: new Map(), listeners: new Map(), lastSeq: 0 };
+}
+
+const store = g[globalKey]!;
+
+const MAX_EVENTS_PER_SESSION = 50;
+const MAX_SESSIONS = 500;
+const TTL_MS = 30 * 60 * 1000;
+
+/** Date-based so ids keep increasing across server restarts. */
+function nextSeq(): number {
+  store.lastSeq = Math.max(Date.now(), store.lastSeq + 1);
+  return store.lastSeq;
+}
+
+function prune(): void {
+  const cutoff = Date.now() - TTL_MS;
+  for (const [sessionId, events] of store.events.entries()) {
+    const last = events[events.length - 1];
+    if (!last || last.seq < cutoff) store.events.delete(sessionId);
+  }
+  // Map keeps insertion order, so the first keys are the oldest sessions.
+  for (const sessionId of store.events.keys()) {
+    if (store.events.size <= MAX_SESSIONS) break;
+    store.events.delete(sessionId);
+  }
+}
+
+function emit(event: ChatbotSessionEvent): void {
+  const set = store.listeners.get(event.sessionId);
+  if (!set) return;
+  for (const cb of set) {
+    try {
+      cb(event);
+    } catch (e) {
+      console.error("chatbot session listener error:", e);
+    }
+  }
+}
+
+export function saveSessionEvent(
+  event: Omit<ChatbotSessionEvent, "seq">,
+): ChatbotSessionEvent {
+  const saved: ChatbotSessionEvent = { ...event, seq: nextSeq() };
+  const events = store.events.get(event.sessionId) ?? [];
+  events.push(saved);
+  if (events.length > MAX_EVENTS_PER_SESSION) events.shift();
+  store.events.set(event.sessionId, events);
+  prune();
+  emit(saved);
+  return saved;
+}
+
+/** Events newer than `afterSeq`, oldest first. */
+export function getSessionEventsAfter(
+  sessionId: string,
+  afterSeq: number,
+): ChatbotSessionEvent[] {
+  return (store.events.get(sessionId) ?? []).filter((e) => e.seq > afterSeq);
+}
+
+export function subscribeSessionEvents(
+  sessionId: string,
+  cb: ChatbotSessionEventListener,
+): () => void {
+  let set = store.listeners.get(sessionId);
+  if (!set) {
+    set = new Set();
+    store.listeners.set(sessionId, set);
+  }
+  set.add(cb);
+  return () => {
+    const s = store.listeners.get(sessionId);
+    if (!s) return;
+    s.delete(cb);
+    if (s.size === 0) store.listeners.delete(sessionId);
+  };
+}
diff --git a/app/lib/types/chatbot.ts b/app/lib/types/chatbot.ts
index 5cadcde0..52ecad1a 100644
--- a/app/lib/types/chatbot.ts
+++ b/app/lib/types/chatbot.ts
@@ -1,25 +1,14 @@
 import type { Node } from "@xyflow/react";
 
-export type ChatbotRole = "system" | "user" | "assistant";
-
-export interface ChatbotMessage {
-  role: ChatbotRole;
-  content: string;
-}
-
-/** Data carried by each LLM node on the flow canvas (unsaved, in-memory). */
 export type ChatbotNodeData = {
   label: string;
   systemPrompt: string;
   configId: string;
   configVersion?: number;
-  maxTokens: number;
-  historyTokenLimit: number;
 };
 
 export type ChatbotLlmNode = Node<ChatbotNodeData, "llm">;
 
-/** Fixed entry/exit points of the flow. */
 export type ChatbotTerminalNode = Node<
   { label: string },
   "flowInput" | "flowOutput"
@@ -27,19 +16,91 @@ export type ChatbotTerminalNode = Node<
 
 export type ChatbotFlowNode = ChatbotLlmNode | ChatbotTerminalNode;
 
-export interface ChatbotMessageRequest {
+export type ChatbotSessionStatus = "active" | "inactive";
+
+/** `complete` once every field the system prompt asks for is collected. */
+export type ChatbotCompletionStatus = "in_progress" | "complete" | "abandoned";
+
+export type ChatbotCollectedFields = Record<string, unknown>;
+
+export interface ChatbotChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface CreateChatbotSessionRequest {
+  name: string;
+  /** Omit for a new chatbot (backend generates one); resend it for the same chatbot. */
+  chatbot_ref?: string;
   config_id: string;
   config_version?: number;
+  contact_ref: string;
   system_prompt: string;
-  history: ChatbotMessage[];
-  /** Omitted on the first call so the bot greets first. */
-  message?: string;
-  max_tokens?: number;
-  history_token_limit?: number;
 }
 
-export interface ChatbotMessageResponse {
+export interface CreateChatbotSessionResponse {
   success: boolean;
-  data?: { messages: ChatbotMessage[] } | null;
+  data?: { session_id: string; chatbot_ref: string } | null;
   error?: string | null;
 }
+
+export interface ChatbotSessionSummary {
+  session_id: string;
+  name: string;
+  contact_ref: string;
+  chatbot_ref: string;
+  status: ChatbotSessionStatus;
+  completion_status: ChatbotCompletionStatus;
+  collected_fields: ChatbotCollectedFields;
+  config_id: string;
+  config_version: number | null;
+  inserted_at: string;
+  updated_at: string;
+}
+
+export interface ChatbotSessionSummaryResponse {
+  success: boolean;
+  data?: ChatbotSessionSummary | null;
+  error?: string | null;
+}
+
+export interface SendChatbotSessionMessageResponse {
+  success: boolean;
+  data?: { status: string } | null;
+  error?: string | null;
+}
+
+/** Body Kaapi POSTs to our webhook once a session turn completes. */
+export interface ChatbotWebhookPayload {
+  success: boolean;
+  data?: {
+    session_id: string;
+    /** Present on success payloads only. */
+    chatbot_ref?: string;
+    reply?: string;
+    status?: ChatbotSessionStatus;
+    completion_status?: ChatbotCompletionStatus;
+    collected_fields?: ChatbotCollectedFields;
+  } | null;
+  error?: string | null;
+}
+
+export interface ChatbotSessionEvent {
+  seq: number;
+  sessionId: string;
+  success: boolean;
+  reply: string | null;
+  status: ChatbotSessionStatus | null;
+  completionStatus: ChatbotCompletionStatus | null;
+  collectedFields: ChatbotCollectedFields | null;
+  error: string | null;
+}
+
+export type ChatbotSessionEventListener = (event: ChatbotSessionEvent) => void;
+
+export interface ChatbotSessionStoreShape {
+  events: Map<string, ChatbotSessionEvent[]>;
+  listeners: Map<string, Set<ChatbotSessionEventListener>>;
+  lastSeq: number;
+}
diff --git a/app/lib/types/webhookSecret.ts b/app/lib/types/webhookSecret.ts
index 957ef572..d06def7b 100644
--- a/app/lib/types/webhookSecret.ts
+++ b/app/lib/types/webhookSecret.ts
@@ -1,7 +1,7 @@
 export type WebhookSecretFailureReason =
-  | "prompt_improvement_webhook_secret_missing"
-  | "prompt_improvement_webhook_secret_placeholder"
-  | "prompt_improvement_webhook_secret_invalid_format";
+  | "webhook_secret_missing"
+  | "webhook_secret_placeholder"
+  | "webhook_secret_invalid_format";
 
 export interface WebhookSecretResult {
   ok: boolean;
diff --git a/app/lib/utils/chatbotSessionCookie.ts b/app/lib/utils/chatbotSessionCookie.ts
new file mode 100644
index 00000000..818d53b3
--- /dev/null
+++ b/app/lib/utils/chatbotSessionCookie.ts
@@ -0,0 +1,15 @@
+import { AUTH_COOKIE_MAX_AGE, COOKIE_KEYS } from "@/app/lib/constants";
+import { readClientCookie } from "@/app/lib/utils";
+
+/** Session id of the last saved chatbot flow, kept in a cookie. */
+export function readChatbotSessionCookie(): string | null {
+  return readClientCookie(COOKIE_KEYS.CHATBOT_SESSION) || null;
+}
+
+export function writeChatbotSessionCookie(sessionId: string): void {
+  if (typeof document === "undefined") return;
+  const secure = process.env.NODE_ENV === "production" ? "; Secure" : "";
+  document.cookie = `${COOKIE_KEYS.CHATBOT_SESSION}=${encodeURIComponent(
+    sessionId,
+  )}; Path=/; Max-Age=${AUTH_COOKIE_MAX_AGE}; SameSite=Lax${secure}`;
+}
diff --git a/app/lib/webhookCallback.ts b/app/lib/webhookCallback.ts
new file mode 100644
index 00000000..e6e0c822
--- /dev/null
+++ b/app/lib/webhookCallback.ts
@@ -0,0 +1,37 @@
+import "server-only";
+
+import type { NextRequest } from "next/server";
+import { readWebhookSecret } from "@/app/lib/webhookSecret";
+
+/**
+ * Builds the public HTTPS URL the backend should POST async results to.
+ * The shared secret rides along as `secret_value` so the receiving route
+ * can reject forged deliveries.
+ */
+export function buildWebhookCallbackUrl(
+  request: NextRequest,
+  path: string,
+): string {
+  const secretResult = readWebhookSecret();
+  if (!secretResult.ok || !secretResult.secret) {
+    throw new Error(secretResult.reason ?? "webhook_secret_missing");
+  }
+  const configured =
+    process.env.NEXT_PUBLIC_APP_URL ?? process.env.APP_URL ?? null;
+  const base = configured
+    ? configured.replace(/\/$/, "")
+    : `${request.headers.get("x-forwarded-proto") ?? "https"}://${
+        request.headers.get("x-forwarded-host") ??
+        request.headers.get("host") ??
+        request.nextUrl.host
+      }`;
+  return `${base}${path}?secret_value=${encodeURIComponent(secretResult.secret)}`;
+}
+
+/** True when the incoming webhook carries our shared secret. */
+export function isWebhookAuthorized(request: NextRequest): boolean {
+  const secretResult = readWebhookSecret();
+  if (!secretResult.ok || !secretResult.secret) return false;
+  const provided = request.nextUrl.searchParams.get("secret_value");
+  return provided === secretResult.secret;
+}
diff --git a/app/lib/webhookSecret.ts b/app/lib/webhookSecret.ts
index d75add19..ca27ccd3 100644
--- a/app/lib/webhookSecret.ts
+++ b/app/lib/webhookSecret.ts
@@ -21,21 +21,21 @@ export type {
  * surface a specific error code instead of a generic 500.
  */
 export function readWebhookSecret(): WebhookSecretResult {
-  const raw = process.env.PROMPT_IMPROVEMENT_WEBHOOK_SECRET;
+  const raw = process.env.WEBHOOK_SECRET;
   if (!raw) {
-    return { ok: false, reason: "prompt_improvement_webhook_secret_missing" };
+    return { ok: false, reason: "webhook_secret_missing" };
   }
   const trimmed = raw.trim();
   if (PLACEHOLDER_VALUES.has(trimmed.toLowerCase())) {
     return {
       ok: false,
-      reason: "prompt_improvement_webhook_secret_placeholder",
+      reason: "webhook_secret_placeholder",
     };
   }
   if (!HEX_SECRET_REGEX.test(trimmed)) {
     return {
       ok: false,
-      reason: "prompt_improvement_webhook_secret_invalid_format",
+      reason: "webhook_secret_invalid_format",
     };
   }
   return { ok: true, secret: trimmed };