Agentic Homepage

Overview

The agentic homepage is one of three homepage themes you can switch on from Admin → Frontend Settings → Homepage Design:

• Classic Homepage — the original landing page with the existing section layout.
• Modern Detailed Homepage — a cleaner second homepage with full product sections.
• Agentic Homepage — a marketing hero with a live AI chat panel embedded directly in the page, plus all the same downstream sections (How It Works, Features, Testimonials, Pricing, FAQ, CTA).

Switching themes is reversible at any time. The agent's content (greeting, agent name, business context) is preserved when you toggle between themes — it just becomes inactive while a non-agent theme is selected.

When to use it: If you sell a product where prospects ask a lot of pre-sales questions (pricing, plan fit, integrations, "does it do X?"), the agent answers them instantly and qualifies the lead in the same conversation. Ideal for SaaS, agencies, consultancies, and any business where the first website visit usually ends in a form-fill or bounce.

How It Works

The flow is intentionally simple — four steps from visitor to qualified lead:

1. Visitor lands on the homepage. The hero shows your marketing copy on the left and the chat panel on the right (or full-width on mobile). The agent's greeting appears immediately.
2. Visitor fills the intro form. Required: name. Optional: email, company, and a "what brings you here?" use-case dropdown (Pricing & plans / Request a demo / Feature questions / Technical support / Something else). All four fields are captured to the lead row.
3. Visitor chats with the AI. Every message is sent to your configured AI provider (OpenAI, Anthropic, Gemini, or Mistral). The reply is generated synchronously — no polling, no background jobs — and rendered in the chat panel as it returns. The system prompt includes your business context, agent name, and the visitor's profile so answers stay accurate and on-brand.
4. Lead is captured. The full transcript, contact details, AI usage (tokens, cost, model), source page URL, and timestamps are persisted to the homepage_leads table. Your team triages them in Admin → Homepage Leads.

When AI is not configured

If no AI provider has a saved API key, the homepage still renders the full landing page — only the chat panel is replaced with a friendly “AI assistant launching soon” placeholder that surfaces the Login / Get Started CTAs prominently. Admins who are signed in also see a direct link to Admin → AI Providers so the missing-key state is one click away from being fixed.

Activating the Agentic Homepage

The whole feature reuses your existing AI provider keys — there is no separate setup wizard. Three steps:

Step 1 — Configure an AI provider

Open Admin → AI Providers, pick a default provider (OpenAI / Anthropic / Gemini / Mistral) and a default model, and paste the API key for that provider. The AI Providers page shows the same connection state used by the agentic homepage — once a key is saved, the homepage flips from the fallback hero to the live chat panel on the next page load.

Step 2 — Switch on the Agentic Homepage

Go to Admin → Frontend Settings → Homepage Design, pick the Agentic Homepage card, and click Save Homepage Design. The public / URL now renders the agent theme.

Step 3 — Configure the agent

The Agent Configuration panel appears immediately below the theme picker once the Agentic theme is selected:

• AI status tile — live readout of which provider and model the agent is using. Shows green “AI Connected” when ready, amber “AI Not Configured” with a deep link to AI Providers when not.
• Captured Leads tile — total count of leads collected, with a one-click link to the full Homepage Leads list.
• Agent Name — the display name shown in the chat header (default Alex).
• Opening Greeting — the first bubble the visitor sees before typing.
• Business Context — a free-form textarea (up to 5,000 characters) describing your products, pricing, key features, who you serve, and what makes you different. The agent uses this to answer accurately. Required for quality results — the more specific, the better the answers.

Click Save Agent Config. The changes apply immediately — no cache rebuild needed.

Lead Capture & Triage

Every conversation becomes one row in Admin → Homepage Leads. The list view shows:

• Stat tiles — total leads, plus a breakdown by status (new / contacted / qualified / closed / spam).
• Search — matches across name, email, and company.
• Status filter — jump to any pipeline stage.
• Table — visitor (name + email + company), use case, first message preview, message count, status pill, captured time, and a one-click open link.
• Export CSV — downloads every lead with name, email, company, use case, status, message count, AI provider/model, AI cost, and source page URL.

Lead detail view

Clicking a lead opens a two-column detail page:

• Left column — Conversation. The complete transcript with visitor and AI bubbles, timestamps, and inline cost metadata. Scrolls inside its own pane for long chats.
• Right column — Lead info, status, AI usage, and notes:
  • Visitor block — name, email (mailto link), company, use case, source page URL, captured timestamp.
  • Status dropdown — instant change to new, contacted, qualified, closed, or spam. Auto-submits on select.
  • AI Usage panel — provider, model, total tokens in/out, total dollar cost for this single conversation.
  • Internal notes — a private text field your team can use for follow-up details. Up to 5,000 characters.
  • Delete — permanently removes the lead and its transcript. Requires confirmation.

Why a separate Homepage Leads table (not the Contacts CRM)? Homepage leads are anonymous-first — many visitors chat without leaving an email. Mixing them into the workspace Contacts table would pollute segmentation, automation, and reporting. The dedicated table keeps them isolated until your team explicitly qualifies one and promotes it.

API Endpoints

The agent homepage uses three public HTTP endpoints — all session-based (no token), CSRF-protected via the standard web middleware, and throttled at 30 requests/minute per IP.

POST /agent-chat/start

Request body:

{
  "name":     "Sarah",                     // required, max 120 chars
  "email":    "sarah@acme.com",            // optional, validated as email
  "company":  "Acme Inc.",                 // optional, max 160 chars
  "use_case": "pricing",                   // optional: pricing|demo|features|support|other
  "page_url": "https://example.com/"       // optional, max 500 chars
}

Response 200:

{
  "success": true,
  "data": {
    "session_id": "01J0X3K9R2F7H4E5...",   // also stored in HTTP session
    "greeting":   "Hi! How can I help you today?"
  }
}

Response 503 — AI not configured:

{
  "success": false,
  "message": "The AI agent is not configured. Please set an API key under Admin → AI Providers."
}

POST /agent-chat/send

Request body:

{ "message": "What is the pricing for the Pro plan?" }

Response 200 — both turns delivered in one round-trip (no polling needed):

{
  "success": true,
  "data": {
    "user_message": { "id": "u-abc123", "role": "user",  "body": "What is the pricing..." },
    "agent_reply":  { "id": "a-def456", "role": "agent", "body": "Our Pro plan is $49/mo..." }
  }
}

If the AI call fails (timeout, quota, network), the endpoint still returns 200 with a friendly fallback message so the chat never appears broken to the visitor:

{
  "success": true,
  "data": {
    "user_message": { ... },
    "agent_reply": {
      "id":          "a-fallback-...",
      "body":        "I'm having trouble responding right now. A team member will follow up shortly...",
      "is_fallback": true
    }
  }
}

Data Model

Every lead is one row in the homepage_leads table with the following columns:

What customers see

For visitors, the experience is conversational from the first second:

• No form, then a form — the greeting bubble appears first to set the tone. The lead form is right below it, framed as “Start the conversation” rather than “Fill out this form”.
• Instant replies — the typing indicator runs while the AI generates a response. Most replies arrive in 1–3 seconds. There is no polling, so latency is exactly one HTTP round-trip plus the model's compute time.
• Accurate answers — the system prompt includes your business context, so the agent knows your real product / pricing / positioning instead of inventing answers.
• Stays on brand — the chat panel inherits your theme tokens (brand color, surface colors, ink color) so it looks native on the page in both light and dark mode.
• Mobile-ready — on small screens the chat panel stacks below the marketing copy and adapts to the viewport height so the message list scrolls cleanly while the input bar stays pinned.
• Failure-tolerant — if the AI hits a timeout or quota cap, the visitor sees a graceful “a team member will follow up shortly” message rather than a broken state. The transcript is still saved, so your team picks up where the AI left off.

How it differs from a generic chat widget

Best Practices

• Write a focused Business Context. Include the product name, what it does in one sentence, the pricing tiers with numbers, the top 3–5 features, who it's for, and one differentiator. Skip marketing fluff — concrete facts let the AI answer with confidence.
• Pick a fast, cheap model for first contact. gpt-4o-mini, claude-haiku-4-5, gemini-2.0-flash, or mistral-small-latest are all good defaults. Most homepage conversations need speed and accuracy, not deep reasoning.
• Review leads daily, even briefly. The CSV export pairs well with a Slack channel or daily digest workflow. Triage by status in the first 24 hours so qualified ones don't go cold.
• Track AI cost. Every lead row shows the cumulative cost of the conversation. Sum them in the CSV to verify the cost-per-qualified-lead is healthy for your acquisition model.
• Promote qualified leads to Contacts manually. Right now this is a copy-paste from the lead detail view; a one-click promote action is on the roadmap. Keeping it explicit prevents low-quality homepage leads from polluting your CRM segmentation.