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

Attribute	Config Key	Required	Default	Description
data-church-id	churchId	Yes	--	UUID of the church in the churches table
data-color	color	No	#D4AF37 (Sacred Gold)	Hex color for the widget button and chat header
data-position	position	No	bottom-right	Widget position: bottom-right, bottom-left, top-right, top-left
data-welcome-message	welcomeMessage	No	null	Custom greeting shown when the chat window opens
data-base-url	baseUrl	No	https://churchwiseai.com	API base URL (auto-detects localhost for development)
data-agent	agent	No	null	Pre-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:

Tier	Badge Behavior
Basic (auto-provision)	Always shown
Pro Website	Always shown
Starter	Always shown
Pro	Always shown
Suite	Removable 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

• UX Model -- three UX surfaces including the embed widget
• Tier Restrictions -- which tiers get widget access
• Architecture -- full request pipeline including origin validation