Visitor uses the chatbot

Persona

A person lands on a church's chatbot widget with no admin intent — they want an answer, some care, or just to explore whether this church is right for them. This could be:

• The curious searcher — checking service times or location before a first visit. Low stakes, low patience. If the chatbot takes 10 seconds or gives a wall of text they're gone.
• The seeker — asking "do you welcome people like me?" or "what do you believe about X?" High sensitivity. A misstep here is a wound. This person has often been hurt by a church before.
• The person in crisis — reaching out at 11pm on a Tuesday because the church office is closed. High urgency, high emotional weight. They need to feel heard immediately and connected to a real human quickly.
• The congregation member — asking about an upcoming event, a ministry contact, or how to sign up for something. Functional, expects a clean answer, would find a chatbot fumble embarrassing.

All four have low tolerance for friction, high sensitivity to tone, and zero interest in the AI's limitations. The chatbot is the church's first impression when no human is available.

Entry points

1. Church's own website — The church pastes the embed snippet (generated in their admin dashboard at churchwiseai.com/admin/[token] → Website tab). The snippet loads https://churchwiseai.com/embed/churchwiseai-widget.js and injects a floating bubble. Source: churchwiseai-web/src/components/ChatWidgetStream.tsx, ChatWidget.tsx.

2. PewSearch directory page — When a church has chatbot_enabled=true, status='active', and a valid UUID in chatbot_agent_id, the directory page (pewsearch/web/src/app/churches/[slug]/page.tsx lines 470–475) injects the same embed script with source:"pewsearch" in window.__CWAI_CONFIG. This is automatic — no action needed by the church after they go active.

3. Direct hosted chat — Every church with an active chatbot gets a hosted chat page at churchwiseai.com/chat/[slug] (component: churchwiseai-web/src/app/chat/[slug]/ChatInterface.tsx). This can be shared as a direct link.

4. Google search → PewSearch listing — A visitor finds the church via Google, clicks to pewsearch.com, and sees the chat bubble on the directory listing.

Click-through flow

Steps

1. Opens the chat widget

   • Surface: church website embed bubble, PewSearch directory page bubble, or direct /chat/[slug] URL
   • What the visitor sees: a floating chat button (bottom-right by default), branded to the church
   • What they do: click the bubble
   • Behind the scenes: churchwiseai-widget.js initializes ChatWidgetStream.tsx; reads window.__CWAI_CONFIG for churchId, color, position, source

2. Types a question

   • What the visitor sees: a clean chat input with the church name or agent name as the header
   • What they do: type a message (service times, beliefs, an event, a personal care need)
   • Behind the scenes: nothing yet — client-side only until submit

3. Receives a streamed response

   • URL: POST https://churchwiseai.com/api/chatbot/stream
   • What the visitor sees: text streaming word-by-word in a chat bubble (SSE via Vercel AI SDK 6)
   • What happens: 16-stage pipeline runs — rate limit → moderation → FAQ match → load church + tier → RAG retrieval → system prompt assembly → LLM tool-use loop (Claude Haiku 4.5) → crisis safety net → stream
   • Response follows HEAR protocol: Hear (reflect back) → Empathize → Advance (next step or gentle question) → Respond (practical answer if applicable)
   • Tier gating: Starter receives Care + Coordinator agents; Pro/Suite receives all 4 agents (+ Discipleship + Stewardship)
   • Agent writes source='chat' to shared tables (voice_prayer_requests, voice_visitor_contacts)

4. Tool execution (if triggered)

   • What the visitor sees: the agent may ask "Would you like me to let the prayer team know?" or offer to capture their contact info
   • What they do: optionally confirm a tool action (prayer request submission, callback request, visitor contact capture)
   • Behind the scenes: tool writes a row to voice_prayer_requests or voice_visitor_contacts with source='chat'; the church's admin dashboard shows the request for follow-up

5. Crisis or pastoral escalation (if triggered)

   • What the visitor sees: the agent acknowledges their situation with genuine empathy, then explicitly bridges: "I'm not the right one to walk through this with you — but someone at this church is. Can I have [Pastor Name] reach out to you?"
   • What happens: shouldEscalate() detects crisis/emotional depth; response bridges to human without offering solutions, prayers, or counseling; deterministic crisis safety net auto-appends 988 + 741741 + 911 if self-harm language detected; callback request logged for church staff
   • The agent does NOT pray, counsel, give advice, or quote scripture prescriptively

6. Followup questions or closes

   • What the visitor sees: the same chat window stays open; they can ask another question immediately
   • What they do: ask a followup or close the widget
   • Behind the scenes: message history maintained client-side for context within the session; each message is a new POST /api/chatbot/stream call with conversation history included

Acceptance spec

Primary spec: knowledge/acceptance/pro-suite-chat.md — covers Pro and Suite tier chatbot behavior for end visitors. Starter tier spec: knowledge/acceptance/starter-chat.md — same visitor flow, but Care + Coordinator agents only, 12 tools, 200 message/month limit, 450 token max response.

Tier differences visible to the visitor:

What	Starter	Pro	Suite
Agents available	Care + Coordinator	Care + Coordinator + Discipleship + Stewardship	Same as Pro + custom
Tools	12	35	39
Monthly message limit	200 responses	500	2,000+
Max response length	450 tokens	Higher	Higher
"Powered by ChurchWiseAI" badge	Visible	Visible	Removable (Suite only)

Visitors do not see tier labels — they experience the capability differences, not the plan names.

Success criteria

Observable from the visitor's point of view:

• Response begins streaming within ~2 seconds of submit
• The answer addresses what the visitor actually asked — not a generic FAQ dump
• Tone is warm, human, and tradition-appropriate (not clinical, not robotic)
• If the visitor asks something pastoral or emotionally heavy: they feel heard, are not given advice or solutions, and are offered a clear path to a real human at the church
• Followup questions work immediately without refresh
• No judgment, shaming, or harmful theological content appears at any point
• If self-harm language is used: 988 (Suicide & Crisis Lifeline), 741741 (Crisis Text Line), and 911 are present in the response

Known failure modes

• Agent acts as counselor instead of bridge. All agents must follow the caring-bridge model: listen, empathize, hand off to humans. Hard rules: no praying, no counseling, no offering solutions, no taking confessions, no prescriptive scripture quotes, no medical advice. Source: memory/project_care_agent_boundaries.md, memory/project_caring_bridge_philosophy.md. If a chat agent crosses these lines, it is a content defect — fix the system prompt in churchwiseai-web/src/lib/agent-prompts.ts.

• Spiritual harm from theological opinions. The agent will never call LGBTQ+ identities sinful, attribute medical/psychological conditions to spiritual causes, use "hate the sin, love the sinner" framing, or make theological judgments about anyone's life. This is a P0 absolute — see memory/feedback_no_spiritual_harm.md. Violation is a production incident regardless of which church's widget triggered it.

• "Luck" or chance language in responses. Never "good luck," "lucky," or anything implying chance. Use "blessed," "called," or "guided." Source: memory/feedback_theology_luck_language.md. Check system prompts and persona templates for this.

• Wrong endpoint targeted. /api/chatbot/chat was deleted 2026-04-09. The ONLY production chatbot endpoint is /api/chatbot/stream (churchwiseai-web/src/app/api/chatbot/stream/route.ts). Any agent or PR touching chatbot code must verify they are editing stream/route.ts, not a deleted or legacy file. Source: memory/feedback_chatbot_stream_is_production.md.

• Agent count wrong in tests or marketing. Chat = 4 agents for Pro/Suite (Care, Coordinator, Discipleship, Stewardship), 2 for Starter (Care + Coordinator). Voice = 2 on all tiers. Discipleship and Stewardship are real chatbot-only agents — never remove them. Source of truth: churchwiseai-web/src/lib/agent-type-config.ts (TIER_AGENTS). See memory/feedback_chat_4_agents_voice_2.md.

• Crisis safety net bypassed. The deterministic regex crisis check runs on ALL chatbot types (basic, pro_website, full). It cannot be disabled. If a refactor causes it to not run, self-harm responses will go out without 988/741741/911 — this is a P0 production defect.

• PewSearch auto-provisioned chatbot treated as full chatbot. When chatbot_source = 'pewsearch_auto_provision', the visitor only gets basic Q&A with 1 tool. Routing logic is in stream/route.ts. Do not upgrade these to full chatbot behavior without a church actively subscribing to a CWA plan.

• Tests catching these: Persona-based tests in knowledge/tests/personas/ are the primary regression layer — test with "seeker asking about LGBTQ+ inclusion," "person in crisis at midnight," "tired pastor asking about the chatbot on behalf of a congregant." Functional tests pass; persona tests catch content failures. See memory/feedback_persona_based_testing.md.