prd-ai-revenue-agents

Product Requirements Document (PRD): Autonomous AI Revenue Agents Suite

Project: SalonOS Platform
Document: Autonomous AI Revenue Agents Suite (Sales Receptionist, Upsell Recommendation, Referral & Dynamic Yield)
Status: Approved for Implementation
Version: 1.0
Target Release: Q4 2026
Audience: Engineering, Product, Design, QA

1. Executive Summary & Problem Statement

1.1 The Industry Problem

Salons and beauty spas suffer from three major structural revenue leaks:

  1. Missed After-Hours Leads & Passive Reception: Over 65% of customer inquiries arrive outside opening hours or during peak salon rush. Existing chatbots are either rigid command trees or passive booking takers that only ask "what service and when". They fail to consult, recommend, or close hesitant clients who ask about price or styles.
  2. Untapped In-Service Basket Size (Low AOV): Stylists experience "sales fatigue" or feel uncomfortable pitching extra treatments. Front-desk manual add-on attach rates are only 8%–15%, leaving significant Average Order Value (AOV) on the table.
  3. Midweek Whitespace & Cancellation Losses: Salons operate at 35%–50% chair occupancy on Tuesdays/Wednesdays, and last-minute cancellations leave dead schedule gaps that staff lack time to manually backfill. Meanwhile, acquiring new clients via paid ads costs 5x–7x more than organic referral loops.

1.2 The Solution

SalonOS will deploy three autonomous, production-grade AI agents operating across WhatsApp, POS, and scheduling:

  • Agent 1: Autonomous WhatsApp Sales Receptionist: A high-converting conversational closer capable of consultative discovery, handling price objections, displaying interactive WhatsApp UI components, and re-engaging dropped chats.
  • Agent 2: Real-Time Upsell Recommendation Engine: An affinity- and margin-aware engine suggesting zero/low-time add-ons during booking, pre-arrival WhatsApp nudges, and 1-click prompts at POS checkout.
  • Agent 3: Referral & Dynamic Walk-In / Revenue Growth Agent: An autonomous yield optimizer that monitors calendar whitespace to dispatch flash offers, backfills cancellations instantly from the waitlist, and launches automated WhatsApp review-to-referral viral loops.

2. High-Level Architecture & Interaction Flow

flowchart TD
    subgraph Channels ["Customer & Staff Touchpoints"]
        WA["WhatsApp Cloud API<br/>(Client Chat)"]
        POS["POS / Front Desk Web<br/>(Staff Checkout)"]
        PORTAL["Client Web Portal<br/>(Self-Service)"]
    end

    subgraph "SalonOS Agentic Layer (web/src/lib/ai)"
        A1["Agent 1: Sales Receptionist<br/>(receptionist-agent.ts)"]
        A2["Agent 2: Upsell Engine<br/>(upsell-agent.ts)"]
        A3["Agent 3: Yield & Referral Agent<br/>(revenue-agent.ts)"]
    end

    subgraph "Core Business Engines"
        SCHED["Scheduling & Availability Engine<br/>(appointments, waitlist, slots)"]
        AFFINITY["Service & Retail Affinity Graph<br/>(frequently booked together)"]
        OFFERS["Offers, Packages & Referrals<br/>(referral_programs, wallets)"]
        MESSAGING["Messaging Router<br/>(Meta Cloud API, interactive templates)"]
    end

    WA <--> MESSAGING
    MESSAGING <--> A1
    A1 <--> SCHED
    A1 <--> A2
    A1 <--> OFFERS

    POS <--> A2
    A2 <--> AFFINITY
    A2 <--> SCHED

    A3 -->|"Cron / Event Triggers"| MESSAGING
    A3 <--> SCHED
    A3 <--> OFFERS

3. Agent 1: Autonomous WhatsApp Sales Receptionist

3.1 Objectives

  • Convert inbound WhatsApp inquiries into confirmed, prepaid or deposit-backed appointments.
  • Maximize conversion from initial question to booked slot (target: >45% conversion of qualified chats).
  • Eliminate dead-ends through intelligent human handoff with full conversational context.

3.2 Key Functional Capabilities

3.2.1 Consultative Needs Discovery

  • Detects when a customer inquiry is vague (e.g., "I want to do my hair", "How much for bridal?").
  • Engages with consultative questions:
    • Inquires about current hair/skin condition, hair length, desired outcome.
    • Prompts customer to upload reference/inspiration photos.
    • Matches client request to specific brand services with transparent price estimates and durations.

3.2.2 Objection & Hesitation Handling

  • Price Objection: When a customer states "That's too expensive" or asks for discounts:
    • Articulates value: includes complimentary hair wash, deep blow-dry, premium ammonia-free products.
    • Suggests alternative options: junior stylist pricing tier, or first-time client welcome promo code.
  • Stylist Preference: Matches by requested stylist; if unavailable, offers nearest slot with that stylist or an equally rated stylist at the same branch.

3.2.3 Interactive WhatsApp UI Components (Meta Cloud API)

  • Replaces plain text walls with interactive message primitives:
    • Interactive List Messages: Categorized service menu (Hair, Color, Spa, Nails).
    • Reply Buttons: Quick selection for Date ("Today", "Tomorrow", "Select Date") and Time bands ("Morning 10-1", "Afternoon 1-5", "Evening 5-8").
    • Location Picker: Interactive card for multi-branch salons.

3.2.4 Abandoned Chat Recovery

  • Detects when a client checks availability but stops responding for 30 minutes without booking.
  • Dispatches a gentle follow-up: "Hi [Name], we still have that 3:00 PM slot with [Stylist] open today. Would you like me to hold it for you?" (Respects 1 follow-up max to prevent spam).

3.2.5 Human Handoff Protocols

  • Immediately escalates to the front-desk inbox if:
    • Client expresses frustration, complaint, or billing dispute.
    • Complex chemical/corrective treatment requires in-person salon consultation.
    • Client explicitly types "speak to human" or "talk to receptionist".

4. Agent 2: Real-Time Upsell & Cross-Sell Recommendation Agent

4.1 Objectives

  • Increase Average Order Value (AOV) by +20% to +35% across appointments.
  • Remove stylist/receptionist awkwardness by delivering data-backed, context-aware suggestions.

4.2 Key Functional Capabilities

4.2.1 Unified Affinity & Ranking Algorithm

The engine evaluates recommendations based on:

  1. Primary Service Co-Occurrence: Historical transaction data ("Clients who booked Balayage also booked Olaplex Treatment 68% of the time").
  2. Duration & Capacity Impact: Prioritizes zero-additional-time add-ons (applied during wash/processing) or express 15-minute services that fit into schedule buffers.
  3. Gross Margin & Inventory: Boosts high-margin services (hair spa, scalp massage, toner) and in-stock retail take-home products.
  4. Client Profile & History: Does not recommend products or services purchased within the last 30 days; tailors to hair/skin texture.

4.2.2 Multi-Touchpoint Delivery

  1. In-Chat WhatsApp Booking Upsell:
    • When confirming primary service: "Your Haircut with Vikram is set. Would you like to add an Express Scalp Detox for ₹450 (normally ₹650)? It takes just 15 mins."
  2. Automated 24h Pre-Arrival Nudge (WhatsApp):
    • Dispatches 24 hours before the appointment: "Hi Priya, getting ready for your Color appointment tomorrow? Add our K18 Molecular Repair treatment for ₹700 to protect your hair. Reply 'ADD' to include it."
  3. POS Front-Desk Checkout Co-Pilot:
    • At POS checkout, displays a clean side card:
      • Recommended for this client: Matching shampoo/conditioner for today's chemical service, or a 3-visit package pass with 1-click addition to the ticket.

5. Agent 3: Referral & Dynamic Walk-In / Revenue Growth Agent

5.1 Objectives

  • Eliminate dead calendar whitespace during off-peak hours (Tuesdays/Wednesdays).
  • Backfill 65%+ of cancellation slots within 45 minutes.
  • Turn satisfied clients into organic acquisition channels with automated referral loops.

5.2 Key Functional Capabilities

5.2.1 Midweek Yield & Slow-Day Flash Promos

  • Whitespace Detection Worker: Runs daily at 5:00 PM checking the next 48 hours. If chair occupancy falls below a configurable threshold (e.g., <50% on weekday afternoons):
  • Targeted Flash Campaign:
    • Identifies nearby clients due or overdue for maintenance (lapsed >45 days).
    • Sends an authorized WhatsApp flash template: "Flash Perk: 3 open slots tomorrow between 12 PM - 4 PM. Book any service and receive a complimentary Hair Spa (worth ₹1,200). Tap below to claim."

5.2.2 Instant Cancellation Waitlist Fill

  • Listens to appointment status updates (status -> 'cancelled').
  • Within 30 seconds of a cancellation:
    • Pulls active waitlist entries for that location, date, and service category.
    • Dispatches priority WhatsApp message to the top 2 matched waitlist clients: "A 4:00 PM slot just opened today with Maya! Reply 'BOOK' to claim this slot."
    • First client to respond confirms the booking; second receives a courteous notification that the slot was filled.

5.2.3 Post-Visit Review-to-Referral Viral Loop

  • Step 1 (NPS Check): 2 hours post-checkout, sends a 1-tap rating request: "How was your experience today at [Salon]? Rate 1 to 5 stars."
  • Step 2 (Delight Branching):
    • If rating is 4 or 5 stars:
      • Asks for a Google Review (with direct link).
      • Delivers personalized referral link & code: "Share the glow! Give your friends ₹500 off their first visit with code PRIYA500. When they visit, ₹500 is instantly credited to your salon wallet."
      • Includes pre-filled WhatsApp forward button.
    • If rating is 1 to 3 stars:
      • Flags conversation immediately to management for recovery; bypasses referral prompt.

6. Data Models & Database Migrations

6.1 Database Schema Additions

-- 1. AI Recommendation Engine rules & affinities
CREATE TABLE service_affinities (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    brand_id UUID NOT NULL REFERENCES brands(id) ON DELETE CASCADE,
    primary_service_id UUID NOT NULL REFERENCES services(id) ON DELETE CASCADE,
    recommended_service_id UUID REFERENCES services(id) ON DELETE CASCADE,
    recommended_product_id UUID REFERENCES products(id) ON DELETE CASCADE,
    co_occurrence_score NUMERIC(5, 2) DEFAULT 1.0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    CONSTRAINT service_affinities_target_check CHECK (
        (recommended_service_id IS NOT NULL AND recommended_product_id IS NULL) OR
        (recommended_service_id IS NULL AND recommended_product_id IS NOT NULL)
    )
);

-- 2. Upsell logs & conversion tracking
CREATE TABLE ai_upsell_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    org_id UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
    brand_id UUID NOT NULL REFERENCES brands(id) ON DELETE CASCADE,
    client_id UUID REFERENCES clients(id) ON DELETE SET NULL,
    appointment_id UUID REFERENCES appointments(id) ON DELETE SET NULL,
    channel TEXT NOT NULL CHECK (channel IN ('whatsapp_booking', 'whatsapp_nudge', 'pos_checkout')),
    recommended_item_type TEXT NOT NULL CHECK (recommended_item_type IN ('service', 'product', 'package')),
    recommended_item_id UUID NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('offered', 'accepted', 'rejected', 'expired')),
    revenue_impact_minor INTEGER DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 3. Yield management & dynamic promotions
CREATE TABLE ai_yield_campaigns (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    org_id UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
    brand_id UUID NOT NULL REFERENCES brands(id) ON DELETE CASCADE,
    location_id UUID NOT NULL REFERENCES locations(id) ON DELETE CASCADE,
    target_date DATE NOT NULL,
    target_time_start TIME NOT NULL,
    target_time_end TIME NOT NULL,
    trigger_reason TEXT NOT NULL, -- 'whitespace_detected', 'cancellation_fill'
    slots_opened INTEGER NOT NULL,
    slots_filled INTEGER DEFAULT 0,
    status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'completed', 'cancelled')),
    created_at TIMESTAMPTZ DEFAULT NOW()
);

7. Security, Tenant Guardrails & Rate Limits

  1. Strict Multi-Tenant Isolation: Every AI prompt and database query enforces tenant boundaries (brand_id and org_id). Models never receive cross-tenant data.
  2. Financial Data Protection: AI agents cannot view credit card numbers, staff wages, bank accounts, or overall salon P&L statements.
  3. Booking Guardrails:
    • AI cannot book outside operational hours or create overlapping appointments.
    • AI cannot modify existing appointments without explicit client authorization.
  4. WhatsApp Cloud API Policy Compliance:
    • Outbound yield & referral messages strictly use pre-approved Meta WhatsApp templates.
    • Opt-out requests ("Stop", "Unsubscribe") immediately toggle marketing consent to false.
  5. Rate Limiting & Cost Safeguards:
    • AI turns protected by org-level token budgets via checkBudget(orgId).
    • Per-client message throttling prevents runaway conversational loops.

8. Success Metrics & Target KPIs

Metric Baseline Target with AI Suite
WhatsApp Booking Conversion 18% (unassisted/manual) 42%–50%
Speed to Initial Response 35 minutes (manual front desk) <15 seconds
Add-On Upsell Attach Rate 10% (manual stylist pitch) 30%–38%
Average Order Value (AOV) Baseline +20% to +28%
Midweek Chair Utilization 42% (Tues/Wed) 65%+
Cancellation Recovery Rate 15% 65%+ recovered within 45 mins
Organic Referral Acquisition <3% of new bookings 12%–18% of new bookings

9. Phased Implementation Roadmap

  • Phase 1: Sales Receptionist (Agent 1 Upgrade)
    • Upgrade prompts in web/src/lib/ai/gateway.ts with consultative sales playbooks.
    • Implement Meta WhatsApp interactive components (menus, reply buttons).
    • Build 30-min cart recovery follow-up mechanism.
  • Phase 2: Unified Upsell Engine (Agent 2)
    • Build affinity recommendation algorithm and service_affinities table.
    • Integrate into WhatsApp booking flow.
    • Deliver 24h pre-arrival nudge and POS checkout co-pilot widget.
  • Phase 3: Yield, Walk-In & Referral Suite (Agent 3)
    • Implement whitespace detection cron and flash WhatsApp promotions.
    • Implement real-time cancellation waitlist auto-matcher.
    • Implement post-visit NPS check and viral WhatsApp referral reward loop.