# Software Factory: Embedded Agent: Floating Widget Add a persistent, floating chat widget that users can toggle on any page. --- The **floating widget** is a toggleable chat interface that floats over your application content. It appears as a launcher button in the bottom-right corner and opens a chat panel when clicked. ## When to use the floating widget Use the floating widget when: - The agent is **supplementary** to your main application (support, help, search assistant) - You want a **low-intrusion** interface that users can open, minimize, and close - You want the agent available on **every page** with one line of code For an agent interface that is part of your page layout, use the [inline panel](/docs/guides/alchemist-embedded-chipp-agent-inline-panel/) instead. ## Basic setup ### 1. Install the feature pack Follow the [installation guide](/docs/guides/alchemist-embedded-chipp-agent-install/) first and check **Floating widget**. The pack adds the Svelte component `web/src/lib/embedded-agent/EmbeddedAgentWidget.svelte`. ### 2. Render the widget Place it once, for example in `App.svelte`: ```svelte ``` On mount, the component calls your project's own session route (`POST /api/embedded-agent/session`; `/api/embedded-agent/session/anonymous` in anonymous mode; in "Both" mode the first, then the second if the visitor is signed out), gets a short-lived chat token, and renders the launcher. ## Component props The component takes one optional prop: | Prop | Type | Purpose | |------|------|---------| | `context` | `Record` | Page context sent with each message, for example `{ page }` | ```svelte ``` Rules for `context`: - Use only keys the binding allows (set in **Settings** > **Embedded agent settings** > **Page context keys**, or from `contextKeys` in `chipp/agent.json`, which replaces that list on every agent sync). The runtime drops other keys. - Never put personal data in it (names, emails, dates of birth, record IDs). The generated component docks to the bottom-right corner. The vendored client in `web/src/lib/embedded-agent/embed-client/` also supports `position: "bottom-left"`, `initiallyOpen`, `launcherLabel`, `panelLabel`, and `onStateChange`; edit the `mountChippEmbedWidget(...)` call in the component to use them. ## Widget behavior - The launcher opens the chat. The open panel has **Minimize chat** and **Close chat** buttons. - The launcher shows an unread badge when the agent replies while the panel is closed or minimized. - On screens 480px wide or narrower, the open panel fills the whole screen and respects the device safe areas. - If the session cannot be minted (the user is signed out, or the feature is not configured), the widget shows "Chat is not available right now." instead of failing the page. ## Authentication & identity The identity mode you chose at install time decides which session route the widget calls. You do not pass identity as a prop. - **Authenticated**: the session route requires a signed-in user in your project and mints the session with that user's ID and email. The widget re-mints the session every 10 minutes so the agent keeps access to your app's tools in a long conversation. - **Anonymous**: the session route mints a pseudonymous visitor session. Nothing is stored in a cookie, so a page reload starts a new visitor and a new conversation. - **Both**: a signed-in user gets an authenticated session; a signed-out visitor gets an anonymous one. When the visitor signs in, the widget upgrades the session and keeps the conversation. After an SPA login (no page reload), call `notifyEmbeddedAgentSignedIn()` from `web/src/lib/embedded-agent/session-client.ts`. See [Session upgrading](/docs/guides/alchemist-embedded-chipp-agent-identity-and-billing/#session-upgrading-anonymous-to-authenticated). ## Styling & customization The widget uses the same `--chipp-embed-*` variables as the [inline panel](/docs/guides/alchemist-embedded-chipp-agent-inline-panel/#styling--customization), plus these for the floating chrome: | Variable | Default | |----------|---------| | `--chipp-embed-widget-size` | `3.5rem` (launcher size) | | `--chipp-embed-widget-offset` | `1.5rem` (distance from the viewport edge) | | `--chipp-embed-widget-z-index` | `2147483000` | | `--chipp-embed-widget-panel-width` | `380px` | | `--chipp-embed-widget-panel-height` | `600px` | ```css :root { --chipp-embed-widget-offset: 2rem; --chipp-embed-widget-z-index: 50; } ``` ## Troubleshooting ### Widget button not visible - Verify the component is rendered (not inside a conditional that is false). - If another element covers it, check `--chipp-embed-widget-z-index`. - If the widget shows "Chat is not available right now.", the session could not be minted (see below). ### Widget shows "Chat is not available right now." - In authenticated mode, confirm the user is signed in to your project. - Confirm the binding is active in the project's **Settings** tab. - Check your server logs for `Embedded agent session` entries. A missing `CHIPP_PROJECT_CLIENT_KEY` returns 503; a failed mint returns 502. ### Chat resets - Chat tokens last 1 hour. In authenticated mode the widget re-mints every 10 minutes. - In anonymous mode each page load is a new visitor, so a reload starts a new conversation. ## Next steps - **[Inline panel](/docs/guides/alchemist-embedded-chipp-agent-inline-panel/)**: embed a panel as part of your layout - **[Backend client](/docs/guides/alchemist-embedded-chipp-agent-backend/)**: call the agent from your server routes