Widget Embedding & Customization

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)

An administrator configures the widget through the admin panel: choosing colors, fonts, layout variants (compact, full-screen, side drawer), and default messages. Every configuration option is validated by the server before it's saved:
- Colors are checked for accessibility (sufficient contrast between text and background)
- Custom CSS is checked against a safe list of allowed properties (preventing malicious styling)
- Localized strings are checked for length limits to prevent layout breakage

Before going live, administrators can open a sandboxed preview — a safe, isolated environment where the widget renders exactly as it will appear on a real customer site. This preview:
- Uses real configuration data, so what you see is exactly what customers will see
- Is completely isolated from production — nothing in the preview affects live users
- Updates in real time as you adjust settings

The embedding process is designed to be simple and secure:

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.

If a new configuration causes problems, rolling back is immediate. An administrator can revert to any previous configuration version from the dashboard, and the change takes effect within seconds — no deployment needed.

---

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.