geolocal-io/docs/product/use-cases/uc-04-conversational-ssp-first-hour.md

# UC-04 — Conversational SSP: The First Hour

**Status:** Spec
**Business model:** Model 1 — Endpoint enablement (conversational activation)
**Primary surface:** GeoLocal.io landing page with embedded chat interface
**Priority:** P0 (replaces form-based SSP as primary activation path)
**Supersedes:** form-based SSP screens in `ssp-refined.md` §3 (Screens 1–5)

---

## 1. Problem

The form-based SSP requires a business owner to fill out structured fields across five screens — a friction-heavy process that assumes technical comfort and patience. Many small business owners will abandon before completing it, even when they want to be discoverable by AI assistants. The experience also fails to demonstrate *why* this matters until late in the flow.

A conversational interface lowers the barrier dramatically: the owner tells the system what they do in natural language, and the AI guides them through verification, discovery, and activation — proving value along the way rather than asking for trust upfront.

---

## 2. Desired Outcome

Within one conversational session (target: 15–30 minutes), a business owner can:

1. Arrive at GeoLocal.io and immediately understand the value through an animated demo
2. Start a chat and describe their business in plain language
3. Verify ownership via one-time pass code delivered to their website's contact email
4. Receive an automated audit of their current online presence across major platforms
5. Get specific, actionable recommendations to improve discoverability on Google, Apple, Bing, Yelp, and their own website
6. Complete initial setup with the AI's guidance — no forms to fill out manually

The owner leaves the first session with a clear picture of where they stand and a ranked list of steps to become AI-discoverable.

---

## 3. Actors

| Actor | Role |
|-------|------|
| **Business owner** | Primary user; may not be technical; wants more customers |
| **GeoLocal AI** | Conversational interface; guides owner through verification, audit, and recommendations |
| **Verification system** | Delivers OTP to the email address found on the owner's website |
| **Presence audit engine** | Scans the business's footprint across Google, Apple, Bing, Yelp, and the core website |
| **geolocal platform** | Hosted MCP, data persistence, recommendation engine |

---

## 4. Preconditions

- Owner can access GeoLocal.io from any browser (desktop or mobile)
- Owner has a website with a publicly listed contact email (for OTP delivery)
  - **Alternate path:** If no website exists, the owner provides an email directly (see A2)
- Owner is the legitimate business operator (or authorized representative)
- Business has a physical presence or service area (local business)

---

## 5. Main Success Scenario

### Phase 1: Welcome and Discovery

1. **Arrive** — Owner opens GeoLocal.io. The landing page shows:
   - Animated demo of a conversation between an AI and a business owner (visual, not interactive — shows what the experience feels like)
   - Prominent "Get Started" CTA that launches the live chat
   - Brief value statement: "We help local businesses succeed in the AI age"

2. **Start Chat** — Owner clicks "Get Started." The chat opens with:
   - Welcome message: *"Welcome to GeoLocal! We help local businesses succeed in the AI age. Tell me about your business."*
   - The AI waits for the owner's response

3. **Describe Business** — Owner describes their business in natural language (e.g., *"I have a salon in Cameron Park, CA. I want to improve our traffic — can you help?"*)
   - The AI extracts key entities: business type, location, goal
   - The AI confirms understanding: *"Got it — a salon in Cameron Park, CA, and you want more customers. Let's make sure AI assistants can find you and recommend you."*

### Phase 2: Verification

4. **Ownership Verification** — The AI initiates verification:
   - *"Sure, I can help with that! First, let me verify you're the legitimate owner. I'm sending a one-time pass code to the contact email on your website."*
   - The system identifies the website from the owner's description (or asks for it)
   - The system scrapes the website for a contact email address
   - An OTP is sent to that email address
   - The AI prompts: *"Check your email and enter the code here."*

5. **Owner Enters OTP** — Owner types the pass code into the chat
   - The AI validates the code
   - *"Your business affiliation is now verified! I'll review your business's online presence — one moment."*

### Phase 3: Presence Audit

6. **Audit Execution** — The system runs a presence audit (background task, ~30–90 seconds):
   - Scans the business's website for structured data (hours, services, contact info)
   - Checks Google Business Profile status and completeness
   - Checks Apple Maps listing
   - Checks Bing Places listing
   - Checks Yelp listing
   - Evaluates overall data consistency across platforms

7. **Audit Results** — The AI presents findings conversationally:
   - *"This looks like a terrific salon! I found your listing on Google and Yelp, but there are a few gaps. If we optimized a few things, AI assistants would find you and recommend you to their users much more often."*
   - Specific findings (not generic): *"Your Google listing doesn't include your services. Your website doesn't have structured hours. Yelp has your old phone number."*

### Phase 4: Recommendations and Setup

8. **Actionable Steps** — The AI presents a ranked list of specific actions:
   - *"Here's what I recommend, in order of impact:"*
   - Each item is concrete and platform-specific:
     - *"Add your services to your Google Business Profile (takes 5 minutes)"*
     - *"Update your hours on your website so AI can read them"*
     - *"Install a discovery pointer so assistants can find your structured data"*
   - The AI explains the "why" for each recommendation

9. **Guided Completion** — The AI offers to help complete items:
   - *"Want me to help you set up your GeoLocal endpoint? I'll walk you through it."*
   - The AI guides the owner through the remaining setup steps (data capture, pointer install, preflight) — all through conversation
   - No forms: the AI asks questions conversationally and populates the data

10. **First Session Complete** — Owner has:
    - Verified ownership
    - Received a presence audit
    - Started (or completed) initial setup
    - A ranked action list for ongoing optimization
    - Understanding of what's next

---

## 6. Alternate Paths

| ID | Trigger | Behavior |
|----|---------|----------|
| A1 | Owner has no website | AI asks for email directly: *"I don't see a website for your business yet — that's actually one of the things we can help with. What's the best email to reach you?"* OTP sent to provided email |
| A2 | Owner wants to skip verification | AI explains why: *"Verification helps me access your existing listings so I can give you accurate recommendations. Want to skip and do a quick overview instead?"* Limited audit available without verification |
| A3 | Website has no contact email | AI falls back: *"I couldn't find a contact email on your site. Can you tell me the best email for you?"* OTP sent to provided email |
| A4 | Owner is not the actual owner | OTP fails to validate (code not received). AI handles gracefully: *"No problem — the code wasn't accepted. Are you the right person to talk to?"* Soft reject after multiple failures |
| A5 | Owner wants to see the demo first | Landing page animated demo is always visible before clicking "Get Started." Owner can also ask the AI *"Show me what this looks like"* during chat |
| A6 | Multiple locations | AI detects multi-location during discovery. Defers to single-location flow for MVP: *"Let's start with your main location. We can add others later."* |

---

## 7. Exception Paths

| ID | Trigger | Behavior |
|----|---------|----------|
| E1 | OTP delivery fails | Retry up to 3 times with exponential backoff. After 3 failures: *"I'm having trouble reaching that email. Can you try a different one?"* |
| E2 | OTP expires | *"That code has expired. Want me to send a new one?"* |
| E3 | Audit finds no online presence | *"I couldn't find your business listed anywhere online yet. That's actually great news — we're going to set that up from scratch. Let's start with your basic info."* |
| E4 | Owner abandons mid-conversation | Session state is preserved. Owner can return later and resume: *"Welcome back! We were working on your salon's setup. Want to pick up where we left off?"* |
| E5 | Business not in ICP | AI detects non-local or non-service business during discovery. Soft redirect: *"We specialize in helping local service businesses right now. Here's what we can do for you…"* |
| E6 | Audit takes too long | *"This is taking longer than expected — your business has a lot of listings to check. I'll have results in about a minute."* |

---

## 8. Functional Requirements (Product)

### Landing Page
- Animated demo showing a sample conversation (visual, non-interactive)
- "Get Started" CTA — single click to launch chat
- Value proposition: clear, one-line statement
- Mobile-responsive

### Conversational Interface
- ChatGPT-like experience in the browser (full-width chat UI)
- Natural language input (text; voice deferred)
- AI responds in conversational tone (warm, helpful, expert)
- Session persistence (resume after interruption)
- Typing indicators during audit/processing

### Verification
- OTP generation and delivery via email
- Website scraping for contact email extraction
- OTP validation (time-limited, single-use)
- Graceful fallback when website email unavailable

### Presence Audit
- Automated scanning of business presence across platforms:
  - Google Business Profile
  - Apple Maps / Apple Business Connect
  - Bing Places
  - Yelp
  - Business website (structured data, contact info, hours, services)
- Gap analysis: what's missing, what's inconsistent, what's outdated
- Conversational results delivery (not a report PDF)

### Recommendations
- Ranked, platform-specific action items
- "Why it matters" explanation for each item
- Guided completion: AI helps owner execute steps
- Progress tracking within the session

### Data Capture (Conversational)
- AI asks questions conversationally to populate business data
- No forms: data enters through natural dialogue
- AI confirms understanding before saving
- Editable: owner can correct or update at any time

---

## 9. Conversation Flow Requirements

The AI conversation is driven by **workflow scripts** that structure the flow, with a hosted LLM (8–12B parameter model, TBD) handling natural language within that structure. Key constraints:

- **Workflow-driven, not free-form:** The AI follows a defined state machine (welcome → discovery → verification → audit → recommendations → setup). It does not wander off-topic.
- **Natural language within structure:** The AI translates structured steps into warm, conversational responses. It asks one question at a time, doesn't overwhelm.
- **Tone:** Helpful expert — not salesy, not robotic. The AI is a guide, not a form with a chat skin.
- **Pacing:** One topic per turn. Don't ask for address, hours, and services in the same message.
- **Confirmation:** After extracting data, the AI confirms: *"So you're Maria's Hair Salon in Cameron Park, open Monday through Saturday. Did I get that right?"*

---

## 10. Success Metrics

| Metric | Definition | Early Target |
|--------|------------|--------------|
| Chat start rate | Visitors who click "Get Started" | Track; optimize landing page |
| Verification completion | Owners who complete OTP | >70% of started sessions |
| Audit-to-action conversion | Owners who start implementing recommendations | Track per session |
| First session duration | Time from "Get Started" to session end | 15–30 minutes target |
| Abandonment rate | Sessions abandoned before verification | <30% |
| Owner satisfaction | "I understand what to do next" after session | Qualitative; interview first 20 |

---

## 11. Out of Scope for UC-04

- Voice input (deferred)
- Multi-language support beyond English (deferred)
- Multi-business accounts (deferred)
- Real-time co-browsing or screen-sharing
- Automated fixes applied by the AI (owner executes; AI guides)
- Ongoing relationship features (see UC-05)
- Form-based fallback (chat is the only path — see decision record)

---

## 12. Dependencies

- Landing page with animated demo
- Chat UI component (in-browser, full-width)
- Hosted LLM (8–12B model, TBD provider)
- Workflow script engine
- Email delivery service (OTP)
- Website scraper (contact email extraction)
- Presence audit engine (Google, Apple, Bing, Yelp)
- Data persistence (session state, business data)
- MCP endpoint (for post-setup activation — reuses UC-01 mechanics)

---

## 13. Open Questions

1. What is the minimum viable presence audit? Do we check all five platforms in MVP, or start with Google + website?
2. How long should OTP codes be valid? (Proposal: 10 minutes)
3. How many OTP retries before hard block? (Proposal: 3)
4. Should the animated demo be video or CSS animation?
5. Do we save partial sessions indefinitely or set a TTL?
6. What happens when the audit finds the business is already well-optimized? (Happy path conversation)
7. Should the AI offer to book a follow-up call for complex cases?