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.

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.

Roadmap Alignment

• Immediate Relief (Today): 2-minute install, combined key auth, credit billing, AI transcript analytics.
• Near-Term (Next Quarter): Prompt version control, A/B testing, compliance report automation.
• Long-Term (Next Year): Voice/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.