# Theo · Embeddable Chat Widgets

> Theo iframes are white-label chat widgets that drop onto any site. Backed by an API key, governed by Brand Soul (voice, palette, behaviour), and shielded by abuse heuristics + a bot challenge.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Public URL pattern: /embed/{configId}.
- Auth: ownership tied to a developer's API key. Domain allowlist enforced via CORS.
- Brand Soul: each key carries a curated persona, palette, and behaviour overlay that the widget inherits.
- Preview tokens: short-lived tokens let an unpublished widget be previewed inside the dashboard before going public.
- Abuse defense: layered heuristics (rapid-fire, content repetition, prompt length cap) and an optional bot challenge.

## Authoring loop
1. /dashboard/iframes → create a widget. Pick the linked API key + brand soul.
2. Configure appearance (colors, avatar, greeting), behaviour (welcome messages, suggested prompts, handoff rules), and security (allowed origins, optional bot challenge).
3. Preview it in the dashboard via a preview token.
4. Publish. Copy the embed snippet into the host site.

## Embed runtime
The embed page loads with a context bundle that combines the Brand Soul + appearance + behaviour config. The chat runtime talks to /api/embed/* with the preview token (preview mode) or with the key-derived signed token (public mode). Memory writes flow into the developer's organization, so the AI Worker on the widget retains continuity across sessions if you wire memory in.

## Intent escalation
A keyword fast-path detects "talk to a human", "agent please", and custom keyword triggers. When matched, the runtime emits an intent.escalation event the host site can listen on (postMessage) and optionally route the conversation to a live operator.

## Security
- Frame-ancestors CSP: preview = self only; public = *. Per-key allowedOrigins is the canonical allowlist for CORS on /api/embed/*.
- Geo-blocking is supported by ISO 3166-1 country code. See https://hitheo.ai/llms/guardrails.txt.
- Domain restrictions are enforced server-side; embedding the widget on a non-allowed origin returns a structured error rather than a partial render.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.