Widget Beta
The Elfa Widget puts Elfa's chat, Auto, feed/sentiment, and workspace runtime inside your own product, keyed to your end-users. One widget key serves many end-users: you relay each end-user's identity (and optional personalization + per-user limits) to Elfa, and Elfa tracks sessions, quotas, and attribution per end-user — unlike an API key, which is a single programmatic identity.
There are two ways to integrate it.
The Two Surfaces
| Hosted Widget (iframe) | Headless Widget API | |
|---|---|---|
| What it is | Drop-in embed — our UI in an iframe on your page | Server-to-server REST — your UI, your backend, our runtime |
| Integration | One <script> tag (embed-apollo.js) | Your backend calls /widget-api/v1/* directly |
| Where the widget key lives | Your server (browser holds only a short-lived user token) | Your server — the key is a server secret, never browser-exposed |
| End-user auth | Token minting (get-user-token) + Origin/domain allowlist | Key + inline end-user context on every request; no token minting |
| UI | Ours (themable) | Entirely yours |
| Plan | Free tier and up | Enterprise only |
| Docs | Integration guide on widget.elfa.ai | Quickstart · API Reference |
Both surfaces share the same runtime: the same per-end-user identity, session history, quota accounting, userData personalization, and feature flags. Choosing headless changes who renders the UI and how requests authenticate — not what the widget can do.
Hosted Widget (iframe)
The fastest path: embed the hosted widget with a script tag and configure it declaratively. The interactive playground and the full integration guide live on the widget site — the docs here intentionally do not duplicate them:
- Playground — try it live, tweak config, copy the embed snippet: widget.elfa.ai/demo/apollo
- Integration guide — full embed reference (script tag, config options, theming, token flow): widget.elfa.ai/integration-guide
Headless Widget API
Enterprise partners who want their own UI call the Elfa API directly from their backend under /widget-api/v1/*. Your backend sends the widget key plus the end-user's identity inline on every request — no token minting, no token refresh lifecycle. See:
- Headless Quickstart — auth model, headers, first request, error codes
- Headless API Reference — every endpoint, grouped by capability
Agents building a custom product experience should use Agent Quickstart for cross-product routing, then use Headless Quickstart for widget-key auth and end-user identity handling.
Plans and Keys
| Free | Enterprise | |
|---|---|---|
| Hosted iframe embed | Yes — domain-locked to the playground | Yes — your own domains |
Headless Widget API (/widget-api/v1/*) | No (403 WIDGET_PLAN_NOT_ELIGIBLE) | Yes |
| Capabilities | chat / feed / auto | chat / feed / auto + optional workspace |
Get a widget key from the Elfa Developer Portal:
- Free keys are self-serve and domain-locked to the playground — enough to evaluate the hosted widget.
- Enterprise / production keys (custom domains, headless access, feature flags) are provisioned by the Elfa team — use the portal's Contact us flow or email support@elfa.ai.
If you run both the hosted iframe and a headless integration, use separate widget keys. The iframe model tolerates browser exposure of its key (it is protected by the domain allowlist); the headless surface has no Origin guard, so its key is a pure server secret. Never reuse a browser-exposed key for headless calls.