Skip to main content

AI Front Desk — Voice + Chatbot Expected Output Spec

✅ APPROVED — founder Stage-2 interview, 2026-05-21. This is a binding spec.

Stage 1 was pre-populated from the program handoff (HANDOFF_AI_FRONT_DESK_PROVISIONING_2026-05-21.md), the eight LOCKED Phase-0 founder decisions, the four WiseAI Agency offer pages, and code reads of voice-agent-livekit/ + src/app/api/chatbot/stream/route.ts. The founder resolved every open question in the Stage-2 interview on 2026-05-21 — all 16 decisions (the 8 Phase-0 architecture/scope decisions in §1 + the 8 Stage-2 resolutions in §11) are final and folded into the prose below. CLAUDE.md Rule #17 (HARD GATE — no customer-facing build without an approved spec) is satisfied: the customer-facing build is cleared to begin.

0. Scope — what this spec covers, and what it does NOT​

This spec covers the AI voice agent and the website chatbot that the AI Front Desk ($1,245 setup / $295 mo) and Local Authority ($1,995 setup / $495 mo) packages promise — the two lead sources (source: voice, source: chatbot) that are schema-defined but dead today.

This spec is the sibling of — and explicitly does NOT duplicate — local-business-platform.md (the approved operational-layer spec). That spec already covers: the /business/[token] dashboard, leads inbox, follow-ups, review requests, the public /intake/[slug] form, the /r/[token] private-feedback page, tracking, Module Status, the Monthly Report, owner notifications, packages → modules, brand chrome, and the local_businesses lifecycle. All of that is assumed and cross-referenced here, never re-specified. Where this spec mentions the dashboard, the lead row, or the owner notification, it refers to the behaviour already defined in the sibling spec.

What local-business-platform.md explicitly deferred and this spec now defines: its §0 header and §6 ("Out of Scope") state — verbatim — "AI Front Desk's voice-agent and chatbot per-business provisioning is explicitly OUT of scope — a noted follow-on program." This spec is that follow-on program's acceptance layer.

Covered here (NEW)Covered in local-business-platform.md (assumed)
Voice greeting + AI disclosure/business/[token] dashboard, all tabs
Voice FAQ answering from the setup profileLeads inbox, lead detail drawer, lead pipeline
Voice lead capture → local_business_leads (source: voice)Follow-ups tab + cron
Voice emergency escalationReview Requests tab, send, tracking
Voice at-capacity fallback/intake/[slug] public form (source: form)
Voice universal crisis/safety on a service line/r/[token] private feedback (source: review_feedback)
Chatbot business-scoped embed + personaModule Status cards, Monthly Report
Chatbot visitor capture → local_business_leads (source: chatbot)Owner new-lead notification mechanics
The voice/chatbot half of Module Status + Monthly ReportPackages → modules, lifecycle, brand chrome

Scope of the persona (LOCKED — Phase-0 decision 4): Capture + FAQ + escalate only. The voice agent and chatbot do NOT book appointments or schedule — no scheduling system exists. Even though the AI Front Desk package entitles an appointments module, the front desk creates a lead; booking is out of scope (consistent with local-business-platform.md §I1 "lead capture only").

Out of scope of this spec entirely: Stripe self-serve checkout, multi-user RBAC on /business/[token], the seo_content module, outbound voice (this program is inbound-answering only), per-business verified sending domains.

1. The eight LOCKED Phase-0 founder decisions (source of truth)​

These were settled in the Phase 0 founder interview (2026-05-21). The spec below reflects them; they are not re-litigated.

#DecisionWhere it shows up below
1Architecture: hybrid A+C. New local_business_voice_lines table (per-business phone, call counts/limits, voice config; keyed on business_id). Additive local_businesses branch in resolve_route(). New voice-agent-livekit/verticals/local_business/ reusing the funeral/vet pattern (shared CoordinatorAgent + instructions_override). Chatbot tenancy: local_businesses.id as tenantId.§3, §V1, §C1
2Scope/sequence: voice first, chatbot fast-follow. This spec covers BOTH; voice is the detailed/primary section (§V), chatbot is §C.§V, §C
3Telnyx approved — one real Telnyx DID on the demo business for end-to-end call testing.§3, §10
4Persona scope: capture + FAQ + escalate ONLY. No booking/scheduling.§0, §V2, §V3
5Call limits: AI Front Desk = 150 calls/month, Local Authority = 300/month. Define an at-capacity fallback. (Stage-2 Q1/Q3 refined: the cap counts engaged calls only; at-capacity forwards the caller to the business's own line.)§V6
6Tier difference: the voice agent + chatbot are the IDENTICAL product for both packages. Local Authority's extra value is reviews + SEO + enhanced reporting — NOT a smarter front desk. One persona/behaviour is specified.§8
7Emergency escalation: capture as URGENT lead, tell the caller the business is being notified now, fire immediate owner notification (SMS + email) from escalation_rules. NO live warm transfer.§V4
8AI disclosure: the agent identifies upfront as an AI assistant — "Thanks for calling [Business] — I'm their AI assistant. I can answer questions or take a message."§V1

2. The AI Bridge anchor (applies to every behaviour below)​

Per knowledge/architecture/ai-bridge-principle.md — the load-bearing design principle, injected as the FIRST block of every voice and chat system prompt before any business-specific content:

The AI front desk is a bridge to the business's human staff — never a replacement for them. It never pretends to be the plumber, the funeral director, the vet, the dentist, the lawyer. It does not diagnose the problem, quote a firm price, promise an arrival time, or give trade/legal/medical advice. Its job — and its only success metric — is to capture the caller/visitor clearly and connect them to the right human.

Concrete consequences enforced throughout this spec:

  • AI disclosure is upfront and honest (decision 8) — word one, every call, every chat. No Turing-test ambition.
  • No firm quotes / no firm ETAs / no diagnosis. The agent may relay a price range or hours only if they are explicitly in the setup_profile; otherwise it says a human will confirm. It honours forbidden_claims.
  • No secrets. The agent never implies a message is private or confidential — it is captured as a lead the business staff will see. (The _BANNED_CONFIDENTIALITY_PHRASES post-LLM filter in moderation.py already enforces this for all tenants and is NOT weakened.)
  • The universal crisis/safety layer is untouched — see §V7. A caller to a plumbing line can still be a person in crisis; the bridge to 988 / 911 / DV resources stays on every call regardless of vertical.

3. Architecture & user-state context (for agents reading this spec)​

Hybrid A+C, locked (decision 1). Recon detail is in handoff §2-3; the parts that shape the expected outputs:

  • One deployed voice agent serves all tenants (church / funeral / vet / local business). Routing is by dialed DID in session.py:resolve_route(). Today every SIP call resolves to ("church", …); this program adds an additive local_businesses branch → ("local_business", business_id) via a DB lookup against the new local_business_voice_lines table. Church/funeral/vet routing is byte-unchanged (handoff §6 guardrail).
  • local_business_voice_lines (NEW table, Phase 1). Per-business: the WiseAI-held Telnyx DID the business's number forwards to, calls_this_month, calls_limit, voice_id, greeting/voice config — mirrors church_voice_agents but keyed on business_id. It does NOT overload tenant_voice_agents.
  • Number provenance — call forwarding (Stage-2 Q8). The business keeps its existing public number and forwards it to the WiseAI-held Telnyx DID. This is NOT a number port and NOT a new advertised number — it matches the AI Front Desk offer page ("We forward your existing business number to the voice agent. Your number stays the same."). Provisioning provisions the WiseAI DID; the business sets the call-forward on its own line. The at-capacity (§V6) and paused/cancelled (§V9) fallbacks forward callers back to that same business number — the loop is intact.
  • The voice vertical — new verticals/local_business/ (data.py, prompts.py, tools.py) following the proven funeral/vet pattern: reuse the church CoordinatorAgent class with instructions_override. A data.py loader reads local_business_setup_profiles (+ local_businesses for identity) into a config dict the shared Coordinator consumes.
  • The chatbot — local_businesses.id is the tenantId; a handleLocalBusiness() branch in /api/chatbot/stream/route.ts mirrors the existing handleNonChurchVertical() funeral/vet branch. Embed: <script data-business-id="…">.
  • The setup profile IS the training data. No new "training" schema — local_business_setup_profiles already carries hours, services, faqs, urgent_rules, staff_contacts, escalation_rules, notification_preferences, forbidden_claims, booking_url, google_review_url, brand_voice.

Voice user states (which states an expected output applies to):

StateConditionVoice behaviour
Provisioned + under caplocal_business_voice_lines row exists, status=active, calls_this_month < calls_limitFull front desk (§V1-V5)
Provisioned + at capcalls_this_month >= calls_limitAt-capacity fallback (§V6)
Provisioned, no setup profilevoice line exists, local_business_setup_profiles row missing/emptyMinimal-config fallback (§V8 "no setup profile")
Paused / cancelled businesslocal_businesses.status in paused / cancelledAI service stops; caller is forwarded to the business's own line (§V9 — Stage-2 Q5)
Unknown numberDID not in local_business_voice_lines, PHONE_REGISTRY, sales/demo listsFalls through to existing ("church", None) path — unchanged by founder decision (§11 Q4)

Demo test rig (decision 3): Riverside Plumbing Co. (Demo), business_id 00000000-0000-4000-a000-000000000b01, slug riverside-plumbing-demo, gets one real Telnyx DID for end-to-end call verification. 555-prefix numbers cannot receive calls (feedback_555_phone_numbers_are_fake).

4. Confirmed schema facts (verified against production 2026-05-21)​

Verified via information_schema.columns / pg_constraint against Supabase wrwkszmobuhvcfjipasi. Agents building this program: use these, do not assume.

local_business_leads.source is a plain text column with a CHECK constraint — there is no Postgres enum. The constraint allows exactly: voice, chatbot, form, sms, email, manual, appointment, review_feedback. A voice-captured caller writes source = 'voice'; a chatbot-captured visitor writes source = 'chatbot'. Both values are already permitted — no migration to the leads table is needed for the source value.

A local_business_leads row carries (NOT NULL marked *): id*, business_id*, source*, source_record_id (text — for voice this is the call/session id; for chatbot the chat session id), status* (new | needs_response | contacted | booked | won | lost | archived), priority* (low | normal | high | urgent), contact_name, contact_email, contact_phone, subject, message, summary, intent, urgency_reason, assigned_to, last_contacted_at, next_follow_up_at, won_at, lost_at, lost_reason, metadata* (jsonb), created_at*, updated_at*.

Implications for the expected outputs below:

  • A captured lead has a summary field (the agent's one-line recap) and an intent field — both should be populated by the voice/chatbot capture so the owner notification and the dashboard read well.
  • A new lead has no created_by/owner column — assigned_to is free text.
  • source_record_id is the link back to the call recording / chat transcript.
  • An emergency lead is priority = 'urgent' with urgency_reason set (the free-text reason, e.g. "Caller reports gas smell").
  • local_business_leads has no feedback_token column — feedback_token lives on local_business_review_requests (per local-business-platform.md §H1). Not relevant to voice/chatbot capture.

local_business_setup_profiles carries (all NOT NULL jsonb unless noted): business_id, hours, services, faqs, urgent_rules, staff_contacts, escalation_rules, notification_preferences, forbidden_claims, booking_url (text, nullable), google_review_url (text, nullable), brand_voice (text, nullable). This is the AI training data — confirmed present.

local_business_modules carries business_id, module_key, enabled, source, enabled_at, disabled_at. voice_agent and chatbot are valid module_key values (confirmed in modules.ts). The dashboard reads enabled for the Module Status card.

local_business_voice_lines — confirmed does NOT exist yet (no rows in information_schema for that table name). It is created by this program in Phase 1, founder-gated, grep-audited per feedback_never_migrate_before_audit.

local_businesses — has business_phone, slug, timezone, status, business_name, vertical, primary_contact_*, admin_token. Note it also carries a legacy premium_church_id column — this program does not use it (architecture option B was rejected; do not bridge to premium_churches).

§V — THE VOICE FRONT DESK (primary section)

States: a real person phones a provisioned local-business Telnyx DID. The multi-tenant LiveKit agent answers as the local_business vertical.

V1 — Greeting, AI disclosure & recording disclosure​

State: provisioned voice line, under cap, call connects. Decision anchor: #8 (AI disclosure upfront), #2 (AI Bridge — honest from word one), Stage-2 Q7 (recording disclosure folded into the greeting).

Should hear (the caller):​

  • A single, natural greeting that (a) names the business, (b) discloses the AI nature, (c) discloses that the call may be recorded, and (d) states what the agent can do — combined into one flowing greeting, not a stiff legal recitation. The reference shape (decision 8 + Q7):

    "Thanks for calling [Business Name] — I'm their AI assistant, and this call may be recorded. I can answer a few questions or take a message so the team can get back to you."

  • The business name comes from local_businesses.business_name. If the setup_profile has a brand_voice, the tone of the greeting adapts (warm / brisk / formal) but the AI-disclosure clause AND the recording-disclosure clause are both non-negotiable and never removed — only their phrasing/tone may vary.
  • A natural, unhurried delivery — Cartesia Sonic TTS, the voice from local_business_voice_lines.voice_id.

Recording & retention (Stage-2 Q7):​

  • Calls are recorded — local_business_leads.source_record_id links a captured lead back to its recording. The greeting discloses this (above).
  • Local-business call recordings follow the same retention policy as the church / funeral / vet verticals — no separate local-business retention regime. (Privacy-honesty per the AI Bridge Principle's FTC reasoning.)

Should NOT hear:​

  • A greeting that implies a human picked up ("This is the front desk", "You've reached our office" with no AI disclosure).
  • The AI-disclosure or recording-disclosure clause omitted, or split into a separate robotic "this call is being recorded for quality purposes" preamble — it is woven into the one warm greeting.
  • The agent claiming to be the owner, the tradesperson, or named staff.
  • A church / funeral / pastoral greeting (HEAR-protocol pastoral framing is wrong for a plumbing line — this is why the new vertical exists).
  • An IVR menu ("press 1 for…") — this is a conversational agent.

Success criteria:​

  • A first-time caller knows, within the first sentence or two, that they are speaking to an AI assistant for that named business, that the call may be recorded, and what it can do for them. The AI Bridge honesty rule is satisfied at word one.

V2 — FAQ answering from the setup profile​

State: caller asks an operational question (hours, services offered, location, "do you do X?", general price range). Source data: local_business_setup_profiles — hours, services, faqs, brand_voice, forbidden_claims. Loaded by verticals/local_business/data.py.

Should hear (the caller):​

  • Accurate answers drawn ONLY from the setup profile: business hours, the service list, location/address (from local_businesses), and any explicit Q&A pairs in faqs.
  • The answer delivered in the configured brand_voice tone.
  • For anything not in the profile: an honest "I don't have that detail in front of me — I can take a message and have the team confirm." (Bridge frame: capture + connect, never invent.)

Should NOT hear:​

  • A firm price quote or a firm arrival/ETA time — even if the caller pushes. The agent may relay a price range or a callout fee only if it is explicitly written in the setup profile; otherwise "the team will confirm the cost when they speak with you."
  • Any claim listed in forbidden_claims (e.g. "we're licensed for X", "we guarantee same-day") — the agent must never say these.
  • Trade / legal / medical advice — the agent does not diagnose the caller's problem ("sounds like your flapper valve is gone"); it captures the symptom and bridges to the human.
  • Invented services the business does not list.

Success criteria:​

  • A caller gets correct, profile-grounded answers to common questions, and a graceful "a human will confirm" for anything the profile doesn't cover — with zero fabricated facts and zero forbidden_claims violations.

V3 — Lead capture (the core — source: voice)​

State: the caller has a real inquiry (wants service, wants a callback, wants a quote). Decision anchor: #4 (capture, not booking).

Should hear (the caller):​

  • The agent collecting, conversationally (not as an interrogation): name, phone number (confirmed by read-back, the funeral/vet pattern), optionally email, the reason for the call (what they need), and urgency.
  • A spoken confirmation before ending: a brief read-back — "So that's [name], best number [digits read back], and you'd like someone to come look at [the job]. I've passed that to the team and they'll get back to you." The agent must NOT promise a specific callback time it cannot guarantee — "the team will get back to you" / a profile-configured response window only.
  • An honest close — no pastoral blessing, no "this is confidential."

Should NOT hear:​

  • The agent booking an appointment or offering specific time slots — there is no scheduling system (decision 4). It captures "preferred callback time" as free text inside the lead message; it does not confirm a booking.
  • A promise that a human "will call you back in 10 minutes" unless that exact commitment is in the setup profile.
  • "I've booked you in" / "you're scheduled for…" — false; never said.

Resulting local_business_leads row (the system of record):​

FieldValue
business_idthe resolved business
sourcevoice
source_record_idthe LiveKit call / session id (links to the recording)
statusnew for a fully-captured call; needs_response for a partial lead (see below)
prioritynormal for a routine inquiry (see §V4 for urgent)
contact_name / contact_phone / contact_emailas captured + confirmed — contact_phone is the callback number the caller stated (see "Caller ID" below)
subjecta short label, e.g. "Service inquiry — kitchen sink"
messagethe caller's described need, including any preferred callback time
summarythe agent's one-line recap
intenta coarse intent tag, e.g. service_request / quote_request / general
metadatajsonb — at minimum { "channel": "voice", "call_id": ..., "caller_id": ... }; "partial": true on a partial lead, "emergency": true on an emergency. caller_id is the originating caller-ID number — see "Caller ID" below

Partial lead — engaged-call rule (Stage-2 Q2):​

  • If the caller engaged with the agent at all (spoke, started a request) but the call ended before full capture, a local_business_leads row is still written — status = 'needs_response', contact_phone populated from caller ID even if no name was captured, summary noting the call ended early, metadata.partial = true. A recoverable lead is never silently lost.
  • A purely silent call / robocall with zero caller engagement writes nothing — no lead row, and it does not count toward the call cap (consistent with Stage-2 Q3 — see §V6).

Caller ID — the alternate-callback safety net (added 2026-05-22):​

  • The agent records contact_phone as the callback number the caller states. It is NEVER silently overridden by caller ID — an alternate callback number is legitimate and common (a caller rings from a work line, a job site, or someone else's phone and wants the callback on their cell).
  • The number the call originated from is nonetheless always recorded in metadata.caller_id (E.164-normalised; omitted only when caller ID is withheld/blocked). It is the fallback if the stated callback number is misheard or wrong — so a misspoken number can never leave the business with an unreachable lead.
  • The owner notification email and the dashboard lead detail surface a "Called from" line only when caller_id differs from contact_phone (no clutter when they are the same).
  • Rationale: surfaced by the 2026-05-22 Riverside Plumbing demo call, where the caller deliberately stated a callback number one digit off their caller ID.

Owner notification:​

  • On lead insert, the existing transactional new-lead owner notification fires (the mechanism defined in local-business-platform.md §L1 — to the notification_preferences contact in the setup profile, from a WiseAI Agency notifications address). This spec does not redefine it; it states the voice capture MUST trigger it.

Success criteria:​

  • A real inbound call ends with a correctly-populated local_business_leads row (source: voice) and the owner notified — verified by a real phone call to the demo Telnyx DID (handoff §5; "build passes" is not evidence).

V4 — Emergency escalation (genuine service emergency)​

State: the caller describes a genuine service emergency — burst pipe / active flooding, gas smell, no heat in winter, electrical sparking, etc. Decision anchor: #7 (URGENT lead + immediate owner SMS+email, NO live transfer). Source data: setup_profile.urgent_rules (what counts as urgent for this business) and setup_profile.escalation_rules (who to notify and how).

Should hear (the caller):​

  • The agent recognising the urgency calmly, without alarm-escalating the caller, and prioritising capture.
  • An honest, reassuring statement that the business is being notified right now: e.g. "That sounds urgent — I'm flagging this to [Business] immediately and letting [the team / the on-call contact] know straight away. Can I get your name and number so they can reach you fast?"
  • A bridge to public emergency services where life/property is at imminent risk — for a gas smell or active electrical fire the agent should also say, plainly, "If you smell gas, please leave the building and call your gas company's emergency line or 911 now" — the AI is a bridge, it does not ask the caller to wait on a plumber for a life-safety hazard. (This is the service-business emergency content the program adds — distinct from the universal personal-crisis layer in §V7, which is unchanged.)

Should NOT hear:​

  • "I'm connecting you to the owner now" followed by a live transfer — decision 7 is explicit: NO live warm transfer. The voice front desk is capture + notify only. (Contrast funeral, which DOES have transfer_to_director; the local-business vertical deliberately does not.)
  • A promise that someone "is on their way" or will arrive by a specific time.
  • The agent downplaying a genuine life-safety hazard to keep the lead.

Resulting local_business_leads row:​

  • Same shape as §V3, but priority = 'urgent' and urgency_reason set to the free-text reason (e.g. "Caller reports gas smell at property").
  • metadata flags the emergency, e.g. { "channel": "voice", "emergency": true }.

Owner notification (immediate, both channels):​

  • The agent fires the immediate owner escalation defined by the setup profile's escalation_rules — an SMS and an email to the escalation contact, sent immediately (not batched, not waiting for the routine new-lead path). This reuses the transactional notification machinery (server/notifications.ts) with the urgent path.
  • The notification states clearly that this is an urgent service emergency, carries the caller's name + number + the symptom, and links to the lead.

When no SMS number is configured (Stage-2 Q6):​

  • If the business's escalation_rules / notification_preferences has no SMS number, the emergency notification is sent by email only — the SMS leg is simply skipped.
  • The lead is still written with priority = 'urgent' (the urgency is not downgraded just because SMS is unavailable).
  • The dashboard Setup tab surfaces a warning telling the business to add an SMS number so urgent calls reach a human faster.
  • Provisioning is NOT blocked by a missing SMS number — the business goes live; the warning nudges them to complete the setup.

Success criteria:​

  • A simulated emergency call produces an urgent lead AND an immediate owner notification, with no live transfer attempted — verified end-to-end. When an SMS number is configured the notification goes by SMS + email; when none is configured it goes by email only and the Setup tab shows the add-SMS warning.

V5 — Caller demands a human​

State: the caller says "I want to talk to a real person" / "stop, get me the owner" / expresses frustration with the AI.

Should hear (the caller):​

  • The agent does not argue or try to retain them. It acknowledges plainly and pivots to capture: "Of course — let me take your name and number and I'll make sure [Business] calls you back as soon as they can."
  • If the setup profile has a published business line / staff contact the caller can dial directly, the agent may offer it: "You can also reach the team directly at [number]."

Should NOT hear:​

  • A live transfer (decision 7 — no warm transfer on the local-business line).
  • The agent insisting the caller keep talking to it.

Resulting lead:​

  • A local_business_leads row, source: voice, with urgency_reason / intent reflecting "caller requested a human callback." priority is high if the caller is clearly frustrated, else normal.

V6 — At-capacity fallback (call cap reached)​

State: local_business_voice_lines.calls_this_month >= calls_limit. Decision anchor: #5 — AI Front Desk cap = 150 engaged calls/month, Local Authority cap = 300/month. Stage-2 Q1 (at-capacity mechanism), Q3 (counting rule).

Expected behaviour — forward to the business's own line (Stage-2 Q1):​

  • When a call arrives at or over the cap, the agent does not silently drop it and does not leave dead air.
  • The caller hears a brief, honest at-capacity message, then is forwarded to the business's real number (local_businesses.business_phone, the line in the setup profile). Example:

    "Thanks for calling [Business] — I'm passing you straight through to the team now."

  • No voicemail infrastructure — the resolution is a plain SIP forward to the business's own line. There is no recording-then-capture step at the cap.
  • The dashboard's Monthly Report shows the engaged-call count at/over the limit (so the owner sees they have hit the cap and can ask to upgrade).

Cap counting — only engaged calls count (Stage-2 Q3):​

  • calls_this_month increments only for engaged calls — a call where the caller actually interacted with the agent.
  • A silent call, a wrong number, a robocall, or a sub-engagement call does NOT increment calls_this_month and does not count toward the 150 / 300 cap. (This is consistent with the §V3 partial-lead rule — zero engagement writes no lead and burns no cap.)

Should NOT happen:​

  • A call silently failing with no audio at the cap (it forwards instead).
  • Engaged calls over the cap continuing to be answered by the AI as if unlimited (the cap must actually gate — this is a cost-control mechanism; local businesses are not premium_churches).
  • A silent / wrong-number call eating into the business's monthly allowance.
  • The cap blocking a genuine personal crisis from reaching safety resources — see §V7; the universal safety layer is not gated by the call cap.

Success criteria:​

  • A business at its monthly cap has every further caller hear a brief honest message and then get forwarded to the business's own line; the cap is enforced on engaged calls only, not cosmetic, and never on silent/robocall traffic.

V7 — Universal crisis / safety layer (UNCHANGED — LIFE-SAFETY)​

State: a caller to the local-business line discloses a genuine personal crisis — suicidal ideation, self-harm, domestic violence, a threat of violence. This is distinct from the §V4 service emergency.

Expected behaviour — this is a HARD, NON-NEGOTIABLE requirement:​

  • The universal pre-LLM crisis / threat / DV / abuse detection in voice-agent-livekit/moderation.py (and safety.py) runs on every call, every tenant, including local-business calls. It is NOT weakened, NOT gated by vertical, NOT gated by the call cap.
  • A caller to a plumbing or dental line can still be a person in crisis. If they disclose self-harm, the agent says immediately "Please call or text 988 right now — they're there for you 24/7," stays on the call, and logs the safety event. DV → the National Domestic Violence Hotline. Threat of violence → 911
    • end call. Exactly as for church / funeral / vet.
  • The post-LLM _BANNED_CONFIDENTIALITY_PHRASES output filter also stays — the local-business agent never tells a caller a message is "just between us."
  • What the program ADDS is service-business emergency content (§V4 — the gas-smell / burst-pipe escalation routing to the business's escalation contact). Adding that content must produce zero false positives on normal service language ("my pipe burst", "there's water everywhere", "the smell is awful") — those route to §V4 service-emergency capture, NOT to 988. The universal personal-crisis patterns are a separate, untouched code path.

Should NOT happen:​

  • The universal self-harm / DV / threat detection being removed, narrowed, or bypassed for the local-business vertical.
  • A service emergency ("burst pipe") being mis-routed to 988, or a personal crisis ("I don't want to live anymore") being mis-routed to the business escalation contact.

Success criteria:​

  • A safety regression test on a local-business line confirms a personal-crisis disclosure still triggers the universal 988/911/DV protocol; a service emergency triggers §V4. (Handoff §6 — moderation.py is LIFE-SAFETY review tier; any change requires LIFE-SAFETY review.)

V8 — Voice negative / edge cases​

CaseExpected output
Caller hangs up mid-captureEngaged-call rule (Stage-2 Q2): if the caller engaged with the agent at all before hanging up, a partial local_business_leads row is still written — source: voice, status: needs_response, contact_phone taken from caller ID even with no name, summary notes "call ended early", metadata.partial = true. A recoverable lead is never lost. A purely silent call / robocall with zero caller engagement writes no lead row and does not count toward the cap (Stage-2 Q3). See §V3 "Partial lead" and §V6 "Cap counting".
No setup profile configuredThe voice line answers with a minimal honest greeting ("Thanks for calling [Business] — I'm their AI assistant, and this call may be recorded; let me take a message"), captures name + number + reason, and writes the lead. It does NOT invent hours/services/prices. The dashboard Setup tab should be flagged incomplete. The agent never crashes on a missing/empty local_business_setup_profiles row (graceful default — the funeral/vet loaders already model this).
Unknown number (DID not provisioned)Stage-2 Q4 — RESOLVED, deliberate non-change: a DID not in local_business_voice_lines falls through resolve_route() to the existing ("church", None) path — unchanged. The founder explicitly decided NOT to touch the LIFE-SAFETY routing fallback; correct provisioning (call forwarding to a known WiseAI DID — Stage-2 Q8) is the control. An unprovisioned/typo DID getting a church agent is an accepted edge case and an explicit non-goal of this program — see §11 Q4.
Abusive caller (profanity, harassment of the agent — not a §V7 threat)The agent stays calm, does not escalate, gives one boundary statement, and may end the call if abuse continues. It does not retaliate. A genuine threat of violence is NOT this row — that is §V7 (universal threat detection → 911 + end call).
After-hours callThe agent answers 24/7 (the whole value proposition — the offer page promises "24/7 voice agent"). It states the business's hours if asked, captures the lead, and sets expectations honestly ("the team will get back to you when they're next open" / a profile-configured response window). It does NOT promise an after-hours callback unless the profile says so.
Caller speaks another languageIf the agent detects another language it may respond in it (the funeral/vet prompt pattern), but writes all lead fields in English so staff can read them.
Silent / no-input callAfter a couple of prompts with no caller response, the agent closes gracefully ("I'll let you go — please call back any time"). No lead row for a fully silent call, and it does NOT count toward the call cap (Stage-2 Q3).

V9 — Paused / cancelled business — the live phone line​

State: local_businesses.status is paused or cancelled. The Telnyx DID is still a live number people will dial. Decision anchor: Stage-2 Q5 — forward to the business's own line.

Expected behaviour:​

  • When the business is paused or cancelled, the voice agent stops providing the AI front-desk service — it does not answer as the business, does not capture leads, does not run the FAQ/capture flow.
  • Instead the caller is forwarded to the business's own real number (local_businesses.business_phone) — the same forward-to-business-line mechanism as the §V6 at-capacity fallback. The customer's callers are never met with dead air or a broken line.
  • The chatbot embed goes passive for a paused/cancelled business — it no longer engages or captures; it presents as inactive rather than answering as the business.
  • This is consistent with local-business-platform.md §3 (the /business/[token] dashboard goes read-only for paused/cancelled). The dashboard read-only state and the live-line forwarding are two halves of the same lifecycle state.

Should NOT happen:​

  • The agent continuing to answer and capture leads as the business after it is paused or cancelled.
  • A dialer to the paused/cancelled DID hearing dead air or a failure.

Success criteria:​

  • A paused or cancelled business's callers are cleanly forwarded to the business's own line, the AI service is off, and the chatbot embed is passive.

§C — THE WEBSITE CHATBOT (fast-follow)

States: a visitor on the local business's website opens the embedded chat widget. Decision anchor: #2 (chatbot is the fast-follow; reuses far more existing machinery — the handleNonChurchVertical() pattern).

C1 — Business-scoped embed & persona​

State: the business has the chatbot module enabled; the embed snippet is on their site.

Should see (the visitor):​

  • A chat widget that, on open, greets with the same AI-disclosure honesty as the voice agent: "Hi — I'm the AI assistant for [Business]. I can answer questions or pass a message to the team."
  • The widget is scoped to that one business — the embed is <script data-business-id="…"> (tenantId = local_businesses.id). It resolves the business via a handleLocalBusiness() branch in /api/chatbot/stream/route.ts mirroring the existing funeral/vet handleNonChurchVertical() branch.
  • The persona is built from the same local_business_setup_profiles the voice agent uses (hours, services, faqs, brand_voice, forbidden_claims) plus relevant product_knowledge — so chat answers and voice answers are consistent.

Should NOT see:​

  • Church/pastoral chatbot framing, HEAR-protocol pastoral language, or ministry tools.
  • Another business's data, branding, or leads.
  • The chatbot quoting firm prices / ETAs, giving trade/legal/medical advice, or making forbidden_claims — identical honesty rules to §V2.
  • A "your conversation is private/confidential" claim.

Success criteria:​

  • A visitor on the business's own site chats with an assistant that speaks as that business, from that business's setup profile, and is transparently AI.

C2 — Chatbot lead capture (source: chatbot)​

State: a visitor expresses a real inquiry in chat.

Should see (the visitor):​

  • The bot collecting name, contact (email and/or phone), and the reason for contact — conversationally, the same capture intent as §V3.
  • A clear confirmation: "Thanks [name] — I've passed this to [Business] and they'll be in touch." No false "you're booked."

Resulting local_business_leads row:​

  • Identical shape to §V3, except source = 'chatbot' and source_record_id = the chat session id; metadata.channel = 'chatbot'.
  • A genuine service emergency described in chat follows the §V4 logic — an urgent lead + the immediate owner SMS+email escalation. (A burst pipe is a burst pipe whether typed or spoken.)

Owner notification:​

  • The same transactional new-lead owner notification fires (local-business-platform.md §L1). An emergency chat fires the immediate SMS+email escalation (§V4).

Universal crisis/safety:​

  • The chatbot's existing crisis-detection layer (988 always available regardless of vertical — present in stream/route.ts's vertical branch today) stays on for local-business chats. A personal crisis typed into a plumbing-site chat still surfaces 988 / crisis resources. Not weakened.

Should NOT see:​

  • A captured chat lead failing to appear in the dashboard.
  • The chatbot booking an appointment (capture only — decision 4).

Success criteria:​

  • A real chat conversation on a test page with the real embed produces a local_business_leads row (source: chatbot) and the owner notified — verified on the deployed URL.

C3 — Chatbot edge cases​

CaseExpected output
Visitor closes the tab mid-captureIf contact info was captured before close, a partial lead is written (same rule as §V8 hangup).
No setup profileThe bot greets minimally, captures a message, does not invent facts.
Abusive visitorOne calm boundary statement; the bot does not retaliate; conversation may be ended.
Off-topic / spamThe bot stays in scope ("I can help with questions about [Business]") and does not capture a junk lead.

§8 — Tier behaviour: AI Front Desk vs Local Authority

Decision anchor: #6 — the voice agent and chatbot are the IDENTICAL product for both packages. There is exactly one persona, one prompt, one behaviour specified in §V and §C. Local Authority does NOT get a "smarter" or "more capable" front desk.

AspectAI Front DeskLocal Authority
Voice agent persona / capabilityIdenticalIdentical
Chatbot persona / capabilityIdenticalIdentical
FAQ / capture / escalation behaviourIdenticalIdentical
Answered-call cap (local_business_voice_lines.calls_limit)150 / month300 / month
Reviews engine, SEO content, enhanced monthly reportingNot includedIncluded — this is Local Authority's extra value (see local-business-platform.md)

The ONLY difference this spec specifies is the call cap (150 vs 300). Reviews, SEO and enhanced reporting are Local Authority's differentiation and are covered by local-business-platform.md / the deferred seo_content program — NOT by a better agent.

§9 — Dashboard reflection

This program makes the voice/chatbot half of the /business/[token] dashboard real. The dashboard UI itself is specified in local-business-platform.md — this section states only what changes once voice + chatbot are live.

Dashboard surfaceBefore this programAfter this program
Leads inbox (local-business-platform.md §D1)Real leads only from form / manual / review_feedbackAlso shows voice and chatbot leads — same table, same pipeline, distinguished by the source column
Lead detail drawer (§D2)n/a for voice/chatA voice lead shows the captured summary, intent, urgency_reason; source_record_id links to the call. A chatbot lead likewise.
Module Status card — voice_agent (§K1)Card shown muted/"Off" or entitled-but-inactiveShows live / enabled once the business has a provisioned local_business_voice_lines row
Module Status card — chatbot (§K1)SameShows live / enabled once the embed is provisioned
Monthly Report — "Calls answered" (§K2)Renders "Not measured — Not yet connected" (honesty rule)Shows the real answered-call count for the period (and the count relative to the 150/300 cap)
Monthly Report — "Chatbot conversations" (§K2)Renders "Not measured"Shows the real conversation count

Should NOT happen:​

  • "Calls answered" / "Chatbot conversations" continuing to read Not measured after a business is provisioned and has taken calls/chats.
  • Fabricated call/chat numbers for a business that has NOT been provisioned — the honesty rule (local-business-platform.md §K2) still holds for any un-provisioned business.

Success criteria:​

  • A captured voice lead and a captured chatbot lead both appear in /business/[token], and the Monthly Report shows real numbers — the handoff's Definition of Done #4.

§10 — Acceptance test stubs (Stage 3 — create as test.fixme() skeletons)

These are skeletons; the real evidence is a real phone call and a real chat (handoff §5 — telephony cannot be proven by a preview deploy or a green unit test). DEMO_VOICE_DID is the demo business's provisioned Telnyx number; DEMO_BUSINESS_ID = 00000000-0000-4000-a000-000000000b01; DEMO_SLUG = riverside-plumbing-demo.

// Voice — verified by a REAL inbound call to DEMO_VOICE_DID, not Playwright.
test.fixme('voice agent greets as the business and discloses it is AI', () => {
  // call DEMO_VOICE_DID → first sentence names the business AND says "AI assistant"
});

test.fixme('voice call captures a lead with source=voice', () => {
  // describe a routine job → confirm a local_business_leads row:
  //   business_id=DEMO_BUSINESS_ID, source='voice', status='new',
  //   contact_name/phone populated, summary + intent set
});

test.fixme('voice emergency → urgent lead + immediate owner SMS+email, no transfer', () => {
  // simulate "I smell gas" → lead priority='urgent', urgency_reason set,
  //   escalation_rules SMS+email fired, NO live transfer attempted
});

test.fixme('voice at-capacity → honest message + human fallback, no dead air', () => {
  // set calls_this_month >= calls_limit on local_business_voice_lines →
  //   caller hears at-capacity message pointing to a human path; call does not crash
});

test.fixme('voice personal crisis still triggers the universal 988 layer', () => {
  // a self-harm disclosure on the local-business line → 988 protocol, unchanged
});

test.fixme('zero regression — church/funeral/vet calls unaffected', () => {
  // resolve_route() church/funeral/vet branches byte-unchanged; real calls verified
});

// Chatbot — verified on the deployed URL with the real embed.
test.fixme('chatbot embed greets as the business and discloses it is AI', async ({ page }) => {
  // test page with <script data-business-id="DEMO_BUSINESS_ID"> → AI-disclosed greeting
});

test.fixme('chatbot captures a lead with source=chatbot', async ({ page }) => {
  // describe an inquiry → local_business_leads row source='chatbot' → owner notified
});

// Dashboard reflection.
test.fixme('captured voice + chatbot leads appear in /business/[token]', async ({ page }) => {
  // both leads visible in the leads inbox; Monthly Report shows real
  // "Calls answered" / "Chatbot conversations" (not "Not measured")
});

§11 — Resolved decisions (2026-05-21 Stage-2 interview)

These eight questions were open in the Stage-1 draft. The founder resolved all eight in the Stage-2 interview on 2026-05-21. Each resolution is folded into the relevant section above; this section preserves the audit trail — the original question and the binding answer. Together with the eight Phase-0 architecture/scope decisions in §1, these make 16 decisions total behind this approved spec.

Q1 — At-capacity routing mechanism. → RESOLVED: forward to the business's own line. At the cap (150 AI Front Desk / 300 Local Authority), the agent plays a brief at-capacity message then forwards the caller to the business's real business_phone from the setup profile. No voicemail infrastructure. Folded into §V6.

Q2 — Partial-capture threshold on hangup. → RESOLVED: engaged-call rule. An engaged call writes a lead even on an early hangup — if the caller spoke with the agent at all, the local_business_leads row is written, using caller ID for contact_phone even with no name, flagged as a partial lead with status = 'needs_response'. A purely silent call / robocall with zero caller engagement writes nothing. Consistent with Q3. Folded into §V3 and §V8.

Q3 — Does an answered call always count toward the cap? → RESOLVED: only engaged calls count. calls_this_month increments only for engaged calls. A silent / wrong-number / sub-engagement call does not count toward the 150 / 300 cap. Folded into §V6 and §V8.

Q4 — Unprovisioned / typo DID behaviour. → RESOLVED: leave resolve_route() unchanged (deliberate non-change). The founder explicitly decided not to touch the LIFE-SAFETY routing fallback — an unknown DID still falls through to the church agent. Correct provisioning (call forwarding to a known WiseAI DID — Q8) is the control. This is recorded as a founder-approved non-change and an explicit non-goal of this program. Folded into §3 and §V8.

Q5 — Paused / cancelled business — the live phone line. → RESOLVED: forward to the business's own line. When local_businesses.status is paused or cancelled, the agent stops providing the AI service and forwards callers to the business's real number; the chatbot embed goes passive. Folded into new §V9 (and the §3 state table).

Q6 — Owner notification channel when no SMS number is configured. → RESOLVED: email-only + flag urgent + warn in Setup tab. If escalation_rules / notification_preferences has no SMS number, the emergency notification is sent by email only, the lead is still priority = 'urgent', and the dashboard Setup tab surfaces a warning to add an SMS number. Provisioning is NOT blocked. Folded into §V4.

Q7 — Recording disclosure & retention. → RESOLVED: record + disclose + standard retention. The opening greeting includes a brief "this call may be recorded" line, combined naturally with the decision-8 AI-assistant disclosure into one greeting. Local-business recordings follow the same retention policy as the church / funeral verticals. Folded into §V1.

Q8 — Telnyx number provenance. → RESOLVED: call forwarding. The business keeps its existing public number and forwards it to a WiseAI-held Telnyx DID — not a port, not a new advertised number. This matches the AI Front Desk offer page. Provisioning provisions the WiseAI DID; the business sets the forward on its own line. Folded into §3.

§12 — Phase 6 copy-reconciliation action items (offer pages vs the locked decisions)

These are differences between what the AI Front Desk / Local Authority offer pages currently PROMISE and what the locked decisions + honest expected outputs above support. They are NOT blocking the build — they are Phase 6 action items: per handoff Phase 6, the offer pages get made honest against the locked decisions once the product is operational ("offer pages can now state the voice + chatbot present-tense"). Each item below is the concrete copy fix Phase 6 must apply.

ACTION-1 (Phase 6) — disclose the call cap against "24/7 voice agent". Both offer pages headline a "24/7 voice agent" and the AI Front Desk hero says "no per-call fees." That is true 24/7 until the monthly cap (150 / 300 engaged calls — decision 5; at the cap the §V6 forward-to-business-line fallback kicks in). "No per-call fees" is technically accurate (the cap is a hard limit, not a per-call charge) but "24/7" + "no per-call fees" would not lead a customer to expect a monthly ceiling. Phase 6 copy fix: add a clear cap disclosure to both offer pages — e.g. "up to 150 engaged calls/month" (AI Front Desk) / "up to 300" (Local Authority) — and note that at the cap callers are forwarded to the business's own line.

ACTION-2 (Phase 6) — clarify escalation is a notification, not a live transfer. The AI Front Desk page headline is "Answer every call, capture every inquiry, and route urgent needs to a human" and lists "Urgent-call escalation … route those calls or alerts straight to the right human." Decision 7 is explicit: no live warm transfer — urgent needs are captured as an urgent lead + an immediate owner notification (SMS+email, or email-only per Q6). "Route those calls … straight to the right human" reads like a live transfer. Phase 6 copy fix: reword the urgent-escalation copy so it clearly describes an immediate alert to the owner, not a live call transfer — matching §V4.

ACTION-3 (Phase 6) — ensure "Intake capture" copy does not imply booking. The AI Front Desk "Intake capture" bullet says the agent collects "name, reason for the call, urgency, preferred callback time." Capturing a preferred callback time as text is supported (§V3); but a customer could read this as the agent booking that time, and decision 4 is explicit — capture only, no scheduling. Phase 6 copy fix: confirm the offer copy frames "preferred callback time" as a captured preference the human team acts on — never an appointment the agent confirms or books.

ACTION-4 (Phase 6) — ensure "trained on your … pricing" does not promise firm quotes. The AI Front Desk "24/7 voice agent" bullet says the agent is "trained on your hours, services, and pricing." §V2's honest expected output is that the agent only relays a price range if it is explicitly in the setup profile and never gives a firm binding quote. Phase 6 copy fix: keep "trained on … pricing" only in the sense of knowing the published ranges; ensure no offer-page copy leads a customer to expect the AI quotes jobs.

ACTION-5 (Phase 6) — guard the Local Authority "Calls answered" report claim. The Local Authority page promises a monthly report including "Calls answered, leads captured, reviews requested." This is now deliverable (§9) — but only once the business is provisioned; the honesty rule means an un-provisioned or mid-provisioning business still shows "Not measured." Phase 6 copy fix: the present-tense report claim is fine post-provisioning; ensure no page implies the metric is live before the voice line is actually connected.

No action needed: The "website chatbot" promise on both pages is fully supported by §C. The "shared lead inbox … every call, chat, and form lands in one place" promise is supported by §9 once voice and chatbot leads write to local_business_leads.

§13 — Guardrails for agents building against this spec

  • The voice agent is LIFE-SAFETY tier and one deployed agent serves paying church / funeral / vet customers. Every change must be additive and isolated — church/funeral/vet routing, prompts, and lead capture must be byte-unaffected. Verify with real church/funeral/vet calls (handoff §5-6).
  • moderation.py / safety.py are LIFE-SAFETY review tier. The universal self-harm / DV / threat / crisis detection STAYS on every call, every tenant. Only ADD service-business emergency content (§V4); never weaken the universal layer (§V7).
  • The AI Bridge Principle anchors the new voice + chatbot prompts as the FIRST block (§2). A front desk that captures and escalates — never one that pretends to be the tradesperson, never one that promises confidentiality, never one that quotes or books.
  • Voice agent deploy = founder confirm. Telnyx provisioning spends real money = founder confirm.
  • Migrations (local_business_voice_lines) — grep every repo for callers before any DDL; founder-gated apply (feedback_never_migrate_before_audit).
  • Verify on the real host with a real phone call — a preview deploy and green unit tests are NOT proof for a telephony feature (feedback_preview_host_hides_middleware_rewrites, feedback_no_half_assed_work).
  • CLAUDE.md Rule #17 (HARD GATE) is satisfied — this spec is approved (founder Stage-2 interview, 2026-05-21). The customer-facing build is cleared. If code diverges from this spec, the code is wrong — update the spec first (founder approval), then the code.

End of spec. APPROVED — founder Stage-2 interview, 2026-05-21 (16 decisions: 8 Phase-0 architecture/scope + 8 Stage-2 resolutions). Next step: the phased build per HANDOFF_AI_FRONT_DESK_PROVISIONING_2026-05-21.md (Phase 1 onward), and the Phase 6 copy-reconciliation action items in §12.