# 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