Skip to main content

Knowledge > Products > Chatbot > Widget Config

Chatbot Widget Configuration

Overview​

The ChurchWiseAI embed widget is a self-contained JavaScript file that churches add to their website. It creates a floating chat bubble that expands into a full chat window. The widget loads an iframe pointing to churchwiseai.com/embed, which renders the ChatInterface component. All API calls go to churchwiseai.com/api/chatbot/stream cross-origin.

Plan requirement: Embed widget is available on Pro and Suite tiers only. Starter churches should use the hosted chat page (/chat/[slug]) or Care Hub (/care/[slug]) instead.

Embed Code​

Churches add this to their website (typically before </body>):

<script src="https://churchwiseai.com/embed/churchwiseai-widget.js"
        data-church-id="your-church-uuid"
        data-color="#D4AF37"
        data-position="bottom-right"
        async></script>

The data-church-id attribute is required. All other attributes are optional with sensible defaults.

Configuration Options​

AttributeConfig KeyRequiredDefaultDescription
data-church-idchurchIdYes--UUID of the church in the churches table
data-colorcolorNo#D4AF37 (Sacred Gold)Hex color for the widget button and chat header
data-positionpositionNobottom-rightWidget position: bottom-right, bottom-left, top-right, top-left
data-welcome-messagewelcomeMessageNonullCustom greeting shown when the chat window opens
data-base-urlbaseUrlNohttps://churchwiseai.comAPI base URL (auto-detects localhost for development)
data-agentagentNonullPre-select an agent type (e.g., pastoral_care, welcome)

Two Configuration Methods​

Method 1: data-* Attributes (Standard Embed)​

The standard approach for churches embedding the widget on their own website. Configuration is read from data-* attributes on the script tag:

<script src="https://churchwiseai.com/embed/churchwiseai-widget.js"
        data-church-id="550e8400-e29b-41d4-a716-446655440000"
        data-color="#1B365D"
        data-position="bottom-left"
        data-welcome-message="Welcome! How can we help you today?"
        data-agent="welcome"
        async></script>

Method 2: window.__CWAI_CONFIG (Dynamic Injection)​

Used by Pro Website templates (PewSearch) where the script tag is dynamically created and cannot have data-* attributes set at parse time. The template sets a global config object before loading the widget script:

<script>
  window.__CWAI_CONFIG = {
    churchId: "550e8400-e29b-41d4-a716-446655440000",
    color: "#1B365D",
    position: "bottom-right"
  };
</script>
<script src="https://churchwiseai.com/embed/churchwiseai-widget.js" async></script>

The widget reads window.__CWAI_CONFIG as a fallback when document.currentScript attributes are not available. This is the pattern used by all PewSearch Pro Website templates:

  • UnifiedTemplate.tsx -- injects __CWAI_CONFIG with the church's chatbot_agent_id and style-specific accent color
  • ProtestantModernTemplate.tsx -- uses Navy (#1B365D) accent
  • NondenominationalCommunityTemplate.tsx -- uses Orange (#f97316) accent

Resolution order: data-* attributes take priority over __CWAI_CONFIG. If both are present, data-* wins for each individual config key.

Widget Behavior​

Initialization​

  1. Script loads and executes in an IIFE (immediately-invoked function expression)
  2. Reads configuration from data-* attributes or __CWAI_CONFIG
  3. Validates churchId is present (logs error and aborts if missing)
  4. Checks window.__churchwiseWidgetInitialized to prevent duplicate initialization
  5. Injects CSS styles into <head> (position variants, animations, mobile breakpoints)
  6. Creates the floating button element (56px circle with chat icon)
  7. Creates the iframe element (hidden, no src yet -- lazy-loaded)
  8. Attaches click handler and Escape key listener

Lazy Loading​

The iframe src is not set until the user clicks the chat button for the first time. This means:

  • Zero performance impact on page load (no iframe, no API calls, no additional HTTP requests beyond the 5KB script)
  • First click incurs a brief load delay as the iframe fetches the chat page
  • Subsequent opens/closes are instant (iframe stays loaded in the DOM)

Chat Window​

  • Desktop: 380px wide, 560px tall, positioned 84px from the widget button edge, rounded corners with shadow
  • Mobile (< 480px): Full-screen overlay (100vw x 100dvh), no border radius
  • Animation: 250ms ease transition (opacity + translateY + scale) on open/close
  • Z-index: Button at 2147483646, iframe at 2147483647 (maximum safe integer values to ensure the widget appears above all page content)

Session Management​

  • Each browser tab generates a unique sessionId (UUID) on first message
  • Session persists for the lifetime of the iframe (until page reload or tab close)
  • Message history is maintained client-side in the ChatInterface component's React state
  • No server-side session storage -- the full conversation history is sent with each API request (truncated to recent messages to stay within token limits)

CORS​

The widget is designed to work cross-origin:

  • Widget JavaScript loads from churchwiseai.com and executes on the church's domain
  • The iframe loads churchwiseai.com/embed (same-origin with the API)
  • All API calls from the iframe go to churchwiseai.com/api/chatbot/stream (same-origin within the iframe)
  • Origin validation in route.ts checks the Origin or Referer header but does NOT hard-block unknown origins, because churches embed on arbitrary domains
  • Suspicious origins (non-trusted, non-custom-domain) are logged for monitoring

Pro Website Integration​

When a church has a PewSearch Pro Website, the widget is automatically embedded in the page template. The integration works as follows:

  1. Template injects config: The Pro Website template (e.g., UnifiedTemplate.tsx) sets window.__CWAI_CONFIG with the church's chatbot_agent_id from the premium_churches table
  2. Script auto-loads: The template appends the widget script tag dynamically
  3. Tier restriction: The chatbot API detects the pro_website source and applies restricted behavior (basic Q&A + prayer only, no advanced tools)
  4. Upgrade CTA: After certain interactions, the chatbot suggests exploring ChurchWiseAI for advanced ministry tools
  5. Color matching: The widget color is set to match the Pro Website template's accent color (not the church's brand color, unless explicitly configured)

"Powered by ChurchWiseAI" Badge​

The chat window displays a "Powered by ChurchWiseAI" badge at the bottom:

TierBadge Behavior
Basic (auto-provision)Always shown
Pro WebsiteAlways shown
StarterAlways shown
ProAlways shown
SuiteRemovable via showBranding config (white-label)

The badge links to churchwiseai.com and serves as both brand attribution and lead generation.

Admin Dashboard Widget Customization​

Pro and Suite churches can customize their widget from the admin dashboard (Settings tab > Embed on Your Website):

  • Visual color picker for the widget button and header
  • Position selector (4 corners)
  • Live preview of the embed code with selected settings
  • Copy button to copy the complete embed snippet with all settings baked in

Code References​

  • Widget script: churchwiseai-web/public/embed/churchwiseai-widget.js
  • Embed chat page: churchwiseai-web/src/app/embed/page.tsx (iframe target)
  • Chat interface component: churchwiseai-web/src/app/chat/[slug]/ChatInterface.tsx
  • Origin validation: churchwiseai-web/src/app/api/chatbot/stream/route.ts (step 3)
  • Pro Website template integration: pewsearch/web/src/components/templates/UnifiedTemplate.tsx (line 538)

See Also​