Widget Embedding & Customization
How the embeddable chat widget is styled, sandboxed, previewed, and securely configured so it fits customer sites while remaining safe and performant.
What Is This Feature?
The widget is the customer-facing interface — the chat bubble that lives on your customers' websites or inside their products. It needs to look like it belongs there: matching their brand colors, fonts, and style. It also needs to be secure: embedded on customer sites means exposure to the open internet, so the widget must be hardened against misuse and manipulation. This deep dive covers how the widget is configured, how customizations are validated and applied, and how you can preview changes safely before they go live.
Why It Matters to Your Business
For most of your customers' end users, the widget *is* your product. It's the surface they interact with. How it looks, how it loads, and how it behaves shapes their entire perception of the AI assistant.
- Brand fit drives adoption. A widget that clashes with a customer's visual design feels like a third-party add-on. One that matches their brand feels native — and native tools get used more.
- Security on customer sites. Your widget runs inside your customers' websites. If it's not properly secured, it could be exploited to inject malicious content or leak data — a serious problem that would affect your customers and their end users. Validation and sandboxing protect against this.
- Confidence before launch. Customers want to see exactly how the widget will look before enabling it for their users. The sandbox preview environment makes this possible without any risk.
- Fast rollback. If a configuration change causes problems — visual glitches, unexpected behavior — the platform supports instant rollback to the last known-good configuration.
How It Works (No Technical Jargon)
Setting Up the Widget
The Preview Sandbox
How It Gets Into a Customer's Site
1. The customer copies a small snippet of JavaScript — the "loader" — and places it in their website's code. This snippet is kept tiny (under 30KB) so it doesn't slow down the page.
2. When a visitor's browser loads the page, the loader fetches a signed, time-limited configuration from the platform. This configuration contains all the styling and behavior settings.
3. The widget renders inside a sandboxed iframe — a browser security boundary that isolates the widget from the surrounding page, preventing it from accessing or modifying anything on the customer's site.
4. When a visitor starts a conversation, a session token is created securely, without any sensitive credentials ever being exposed in the browser.
Rollback
Security Highlights
- API keys and secrets are never included in the widget code that runs in a browser — they stay on the server
- All custom styling goes through server-side validation before it can be applied
- The iframe sandbox prevents the widget from interacting with the host page in unintended ways
- Every configuration change is logged with the author's identity and timestamp
What to Expect on the Roadmap
The team is building:
1. A server-side validation service for widget configurations, with detailed error messages surfaced in the admin UI (estimated 3 weeks)
2. A sandboxed preview iframe in the configuration editor
Once live, your customers will be able to confidently customize their widget, preview the results before launch, and trust that the validation system has their back if something doesn't look right.