FAQ
The bubble appears but messages fail — why?
Section titled “The bubble appears but messages fail — why?”Almost always CORS: the worker only answers origins in its
ALLOWED_ORIGIN list. Check the browser console
for a CORS error and add your site’s exact origin (scheme + host, no trailing
slash, comma-separated for multiple sites). http://localhost:* is always
allowed for development.
Visitors see “Too many requests”
Section titled “Visitors see “Too many requests””The worker rate-limits per IP — 10/minute and 50/hour by default. Raise
RATE_LIMIT_MINUTE / RATE_LIMIT_HOUR if your traffic is legitimate; the
limits exist to cap your Anthropic bill and block abuse.
Does the widget work with a strict Content-Security-Policy?
Section titled “Does the widget work with a strict Content-Security-Policy?”Yes. CDN embeds need cdn.jsdelivr.net in script-src and style-src, and
your worker URL in connect-src. Self-hosting
removes the CDN requirement.
Can I run several widgets on one page or several sites on one worker?
Section titled “Can I run several widgets on one page or several sites on one worker?”Both. Per page: give each widget a unique storageKeyPrefix. Per worker: list
every site in ALLOWED_ORIGIN — but note all sites then share one system
prompt; use per-client configs with separate
workers when bots should differ.
Which model does it use, and can I change it?
Section titled “Which model does it use, and can I change it?”claude-haiku-4-5-20251001 by default — fast and inexpensive, a good fit for
support chat. Set the CLAUDE_MODEL worker variable to any Claude model your
API key can access, and MAX_TOKENS to control response length (default
1024).
What data is stored, and where?
Section titled “What data is stored, and where?”- Conversation content lives only in the visitor’s browser
(
sessionStorage, cleared when the tab closes) and in the request to your worker → Anthropic. The worker stores no message contents. - Analytics (optional, off unless you bind
ANALYTICS_DB): metadata only — timing, token counts, status and error codes, message counts/lengths. - Rate limiting: short-lived per-IP counters in KV.
- Attachments (optional): forwarded to Anthropic and discarded by default; with the R2 backend they are kept for a configurable retention window behind signed URLs. Details in Attachments.
- Voice (optional, off by default): the widget never handles audio and none reaches your worker. The visitor’s browser does the listening, and most browsers send that audio to their own vendor (Google, Apple) to be recognized. Details in Voice.
- Conversation export (optional, off by default): copying or downloading a transcript happens entirely in the visitor’s browser. Nothing is sent to your worker. Details in Conversation export.
How big is the embed?
Section titled “How big is the embed?”About 150 KB gzipped JavaScript plus 3 KB CSS. The bundle includes React, so React sites should prefer the component and share their existing React.
Is it accessible?
Section titled “Is it accessible?”WCAG 2.1 AA: focus trap, full keyboard navigation, ARIA labels, screen-reader announcements, reduced-motion-aware animations. Optional voice input and read-aloud help visitors who find typing or reading difficult. Lighthouse accessibility scores 98/100.
How do I report a security issue?
Section titled “How do I report a security issue?”Privately, per SECURITY.md — please don’t open a public issue for vulnerabilities.