AI Chat Widget – Field Guide

The widget is the fastest way to deliver on the promise inside docs/PROBLEMS.md: give citizen developers and accidental AI owners a trustworthy assistant without waiting for engineering. This guide covers everything from build to production, with persona-specific tips pulled straight from the manifesto.

Why Teams Choose This Path

• Citizen Developer (Sarah, Marketing Ops) – Needs a 2-minute install, combined key auth, and an audit trail even though she lives in Zapier/Make.
• Accidental AI Owner (Mike, SMB) – Needs AI chat that matches his brand, costs $0.01 per conversation, and doesn’t require a dev agency.
• Customer teams (Support, Sales, Community) – Need transcripts, prompts, and compliance evidence when leadership asks “What did the bot say?”

Demeterics solves those 3 a.m. worries with a copy-paste widget, analytics, and SOC 2-ready logs.

Before You Start

1. Gather your website domains (example.com, www.example.com, shop.example.com).
2. Write down the top five questions your visitors ask and the “correct” answers.
3. Confirm brand colors or use the default teal #1DA7A0.
4. Decide how you’ll pay: Demeterics credits (included) or Bring Your Own Key (BYOK) for vendor billing.

Step 1 – Create the Widget

1. Go to AI Chat → Create Agent in the dashboard.

2. Fill in the following:

   • Name – Appears in analytics and inbox ("Sales Guide", "Support Bot").
   • Brand Color – Use a hex value from your site. The widget auto-adjusts text for contrast.
   • Avatar Style – Neutral, Friendly, or Tech.
   • Rate Limit – Conversations per minute (30 for small sites, 100+ for busy sites).
   • Allowed Domains – One per line. Widget renders only on these domains.
   • Default Model – Pick the model you trust today (llama, gpt, claude, gemini). You can change it anytime.

3. Click Create. A preview appears instantly so stakeholders can review the UI before you publish.

Step 2 – Teach the Widget

Every widget starts with a default prompt. This is your “instruction card” for the AI.

1. Click Prompts → default → Edit.
2. Use the template below (or click Recreate for my site and let Demeterics ingest your pages).

You are a helpful assistant for [Business Name].

About the business:
- [What you sell or provide]
- [What makes you different]
- [Shipping / location / hours]

Rules:
- Keep answers short unless the visitor asks for detail.
- Offer prices or policies only when documented below.
- If uncertain, direct them to [contact info].

Important policies:
- Shipping: ...
- Returns: ...
- Contact: ...

3. Set Temperature (0.5–0.7 recommended) and Max Response Length (1024 tokens is a good default).
4. Click Save and test in the preview panel.

Creating Additional Prompts

Use multiple prompts to match campaigns or pages:

• /pricing → Pricing prompt with latest offers.
• /support → Support prompt with ticket escalation steps.
• /black-friday → Seasonal prompt with limited-time messaging.

Route visitors by:

• URL path rules
• UTM parameters
• Custom JavaScript calls

Step 3 – Secure & Throttle

• Domains – The widget refuses to load on sites you haven’t approved. This blocks hotlinking.
• Rate Limits – Prevent abuse and keep spend predictable.
• Metadata – Attach attributes (data-source="landing-page") so analytics show campaign performance.
• Combined Keys – The agent key (DEM-XXXX) links to your provider API key configured in the dashboard. No need to expose vendor keys in your embed code.

Step 4 – Embed in Your Site

Paste the snippet before </body>:

<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXXXXXXXXXX" async></script>
<dem-agent name="default" title="Ask us anything"></dem-agent>

Replace DEM-XXXXXXXXXXXX with your actual agent key from the dashboard.

Works on WordPress, Wix, Squarespace, Shopify, Webflow, Ghost, GoDaddy, GitHub Pages, or any site that allows HTML/JS.

Styling & Customization

The widget supports CSS custom properties for layout and color customization. Override these in your site's CSS:

Layout Variables:

Color Variables:

Example: Custom Colors

<style>
  demeterics-chat {
    --dem-primary-color: #FF6B35;  /* Orange */
    --dem-accent-color: #E55A2B;   /* Darker orange */
  }
</style>
<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXX" async></script>

Example: Black Theme

<style>
  demeterics-chat {
    --dem-primary-color: #000000;
    --dem-accent-color: #1a1a1a;
  }
</style>
<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXX" async></script>

Example: Position on Left Side

<style>
  demeterics-chat {
    --dem-right: auto;
    --dem-left: 20px;
  }
</style>
<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXX" async></script>

Example: Larger Widget

<style>
  demeterics-chat {
    --dem-width: 450px;
    --dem-height: 700px;
  }
</style>
<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXX" async></script>

Alternative: HTML Attributes

You can also set colors via HTML attributes on the custom element:

<script src="https://demeterics.com/widget/embed.js?k=DEM-XXXX" async></script>
<demeterics-chat primary-color="#000000" accent-color="#1a1a1a"></demeterics-chat>

Mobile Behavior

On mobile devices (screen width ≤ 768px), the widget automatically adapts for touch-friendly interactions:

Minimized State (Mobile):

• Compact pill-shaped button (52px height)
• Shows only avatar and control icons
• Title and clear button are hidden
• Positioned 8px from screen edges (reduced from 20px on desktop)

Expanded State (Mobile):

• Automatically goes fullscreen
• No fullscreen toggle button (always fullscreen)
• Full chat interface with header, messages, and input

Mobile CSS Variables:

<style>
  /* Mobile widgets use tighter margins */
  @media (max-width: 768px) {
    demeterics-chat {
      --dem-right: 8px;   /* Closer to screen edge */
      --dem-bottom: 8px;  /* Closer to bottom */
    }
  }
</style>

Desktop vs Mobile Comparison:

Platform Guides

• WordPress
• Wix
• Squarespace
• GoDaddy
• GitHub Pages

Monitoring & Analytics

Once live, Demeterics automatically provides:

• Transcripts – Full prompt + response with timestamps and metadata.
• Cost Tracking – Pay $0.01 per conversation or charge against BYOK vendor billing.
• Inbox – Filter by agent, domain, tag, or status; respond manually if needed.
• Exports – Send transcripts to CSV, BigQuery, or downstream automations.
• Alerts – Get notified when volume spikes or sentiment drops (configurable).

Billing & Credits

• Every account starts with 100 free credits ($1 value).
• Credits never expire with regular usage.
• Buy more anytime via Stripe in the dashboard.
• Bring Your Own Key (BYOK) if you prefer vendor billing while still using Demeterics for logging.
• Refund policy: see /refund—pro-rated monthly refunds plus data export before cancellation.

Persona Playbooks

Marketing Ops / Citizen Developer

• Use combined keys so Zapier/Make automations don’t expose admin access.
• Tag flows with x-dem-campaign for later attribution.
• Add weekly prompts that align with live campaigns; archive old prompts for compliance.

Small Business Owner

• Keep the script snippet saved in your website builder or CMS so you can revert quickly.
• Enable SMS/email alerts for keywords like “order status” or “cancel”.
• Use the nightly digest email to review conversations without logging in.

Compliance / Legal

• Use the dashboard export to share hashed transcripts.
• Document prompt changes with version notes so you can explain any response.
• Reference docs/PROBLEMS.md “Ethics & Responsible Use” section when writing guardrails.

Knowledge Engine

Version 1.3.0+ — Beta Feature

Feature Access Required: Knowledge Engine requires whitelisted access.

To request access, email sales@demeterics.com with:

• Subject: "Feature Access Request"
• Feature name: "Knowledge Engine"

Knowledge Engine enables your AI Chat Widget to answer questions using your private documents. Instead of relying only on prompt instructions, the widget retrieves relevant content from your knowledge base.

Why Use Knowledge Engine?

• Accurate answers: Responses grounded in your actual documentation
• No prompt stuffing: Don't paste entire documents into prompts
• Automatic updates: Change documents, widget responses update automatically
• Citation-ready: LLM references specific documents

Setting Up Knowledge for Your Widget

1. Create a Knowledge Project:

   • Go to Knowledge → Projects → Create Project
   • Upload your documents (PDF, Word, Markdown, HTML)
   • Wait for indexing to complete

2. Attach Project to Widget:

   • Go to AI Chat → Your Agent → Settings
   • Under Knowledge Project, select your project
   • Click Save

3. Update Your Prompt (recommended):

   • Add instructions to use knowledge tools:

You are a helpful assistant for [Business Name].

When answering questions:
1. Search the knowledge base for relevant information
2. If you find relevant content, cite it in your response
3. If no relevant content found, say so and offer alternatives

About the business:
- [Brief description]

How It Works

When a visitor asks a question:

1. The LLM receives knowledge tools (search_knowledge, find_documents, get_summary, get_content)
2. The LLM decides which tools to call based on the question
3. Tool results (document excerpts) are injected into the conversation
4. The LLM generates a response using the retrieved context

Example conversation:

Visitor: "What's your return policy?"

Widget (internally):
  → Calls search_knowledge("return policy")
  ← Retrieves: "Returns accepted within 30 days with receipt..."

Widget response: "Our return policy allows returns within 30 days
with a valid receipt. Electronics must be unopened. Please bring
your item to any store location or ship it to..."

Knowledge Tools Available

Combining with Prompts

Knowledge Engine works alongside your prompt. Use prompts for:

• Brand voice and personality
• Conversation rules and guardrails
• Fallback behavior when knowledge search fails

Use Knowledge Engine for:

• Product information
• Policies and procedures
• FAQs and documentation
• Pricing and specifications

Limitations

• Requires whitelisted access (contact sales@demeterics.com)
• Documents must be indexed before they're searchable
• Large documents may be chunked across multiple retrievals
• LLM may make multiple tool calls, affecting latency

Cost

Knowledge Engine usage is included in your widget conversation cost:

• Document indexing: $0.01 per 1,000 tokens
• Query embeddings: $0.0001 per search
• LLM calls: Standard model pricing

Troubleshooting Knowledge

Widget not using knowledge?

• Verify Knowledge Project is attached in widget settings
• Check your prompt encourages using knowledge tools
• Ensure documents are indexed (check project status)

Wrong answers from knowledge?

• Review and update source documents
• Add more specific documents for common questions
• Use document summaries to guide the LLM

For detailed Knowledge Engine documentation, see Knowledge Engine.

Voice-to-Voice (V2V)

Version 1.2.0+ — Beta Feature

Beta Access Required: Voice-to-Voice requires whitelisted access.

To request access, email sales@demeterics.com with:

• Subject: "Feature Access Request"
• Feature name: "Voice-to-Voice Widget"

Voice-to-Voice enables visitors to have spoken conversations with your AI agent. They speak, the AI listens, thinks, and responds with natural voice.

Enabling Voice-to-Voice

1. Go to AI Chat → Your Agent → Settings
2. Enable Voice-to-Voice toggle (requires whitelisted access)
3. Select a Voice from the Murf.ai voice catalog
4. Optionally provide your own Murf API key (BYOK) for direct billing

How It Works

The widget uses a push-to-talk interface with four states:

Technical Pipeline:

1. STT (Speech-to-Text): Groq Whisper Large V3 Turbo — transcribes user audio
2. LLM: Your configured model (Groq, OpenAI, Anthropic, Gemini) — generates response
3. TTS (Text-to-Speech): Murf.ai Falcon — streams audio back to browser

Streaming Architecture

Voice-to-Voice uses a two-phase streaming design for low latency:

Phase 1 — POST /api/widget/voice:

• Uploads audio recording
• Returns: transcript, response, stream_token
• Text appears in widget immediately

Phase 2 — GET /api/widget/voice/stream?token=X:

• Server-Sent Events (SSE) stream audio chunks
• Web Audio API plays chunks as they arrive
• ~130ms time-to-first-audio with Murf Falcon

Available Voices

Cost Tracking

Voice-to-Voice charges are itemized:

All costs appear in your dashboard with breakdown by component.

BYOK for Voice

Bring Your Own Key (BYOK) is supported for Murf.ai:

1. Get an API key from murf.ai
2. Enter it in AI Chat → Settings → Murf API Key
3. Costs bill directly to your Murf account

Without BYOK, Demeterics managed credits are used.

Limitations

• Requires HTTPS (microphone access)
• 60-second maximum recording time
• Available to whitelisted accounts (beta)
• WebM audio format required (Chrome, Edge, Firefox supported)

Roadmap Alignment

• Immediate Relief (Today): 2-minute install, combined key auth, credit billing, AI transcript analytics, Voice-to-Voice beta.
• Near-Term (Next Quarter): Prompt version control, A/B testing, compliance report automation, V2V GA.
• Long-Term (Next Year): WhatsApp/SMS channels, policy engine, ROI dashboards for the board.

Track progress in the changelog or ask support for roadmap updates.

Voice Input (Speech-to-Text)

Version 1.1.0+

The AI Chat Widget includes optional voice input using the browser's built-in Web Speech API. This feature is best-effort—if the browser doesn't support speech recognition, the microphone button simply won't appear.

How It Works

1. Capability Detection: On load, the widget checks if window.SpeechRecognition or window.webkitSpeechRecognition is available.
2. Secure Context Required: Voice input requires HTTPS (or localhost for development).
3. Graceful Degradation: If STT isn't supported, the widget works normally without the mic button.

Platform Support

User Experience

When supported:

• A microphone icon appears next to the send button
• Click to start listening (icon changes to stop, button pulses red)
• Speak your message—interim text appears as you talk
• Click again to stop, or let it auto-stop after silence
• Final transcript appends to any existing text in the input field

When not supported:

• No microphone button appears
• Widget functions normally with text input only

Error Handling

The widget handles common speech recognition errors gracefully:

Privacy & Security

• No cloud processing: Voice is processed entirely in the browser using the Web Speech API
• No audio storage: Demeterics never receives or stores audio data
• HTTPS required: Ensures secure microphone access
• User-initiated only: Recording only starts when user clicks the mic button

Customization

The voice input feature is automatically enabled when supported. No configuration is required. The mic button inherits your widget's brand color scheme.

Troubleshooting

• Widget doesn't render? Confirm domain allow-list and that the script is before </body>.
• Responses feel off? Lower temperature, rewrite the prompt with specific do/don't lists, or assign a different model.
• Costs look high? Adjust rate limits, reduce max tokens, or switch to BYOK for that agent.
• Mic button not showing? Check that you're on HTTPS and using a supported browser (Chrome/Edge recommended).
• Voice input not working? Ensure microphone permissions are granted in browser settings.
• Need help? Email support@demeterics.com or open the chat widget inside the dashboard.

Demeterics gives you the adapter that bridges “we should have AI chat” and “we know exactly what it said, what it cost, and whether it worked.” Use this guide alongside docs/getting-started to keep your implementation aligned with the manifesto.