Published in Factory operations
Embedded Agent: Inline Panel
The inline panel is a native chat interface that lives in your application alongside other content. Unlike the floating widget, it is part of your page layout and does not float over content.
When to use the inline panel
Use the inline panel when:
- You want the agent on a dedicated page or section (for example a “Chat” or “Assistant” page)
- The agent is a core feature of your application, not supplementary
- You need control over where the panel appears (sidebar, main column, modal, and so on)
For a launcher button that floats over your site, use the floating widget instead.
Basic setup
1. Install the feature pack
Follow the installation guide first and check Inline panel. The pack adds the Svelte component web/src/lib/embedded-agent/EmbeddedAgentPanel.svelte.
2. Render the panel
Import it in any page and place it where the chat should appear:
<script lang="ts">
import EmbeddedAgentPanel from "$lib/embedded-agent/EmbeddedAgentPanel.svelte";
</script>
<main class="page">
<EmbeddedAgentPanel />
</main>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 chat. The panel has a minimum height of 20rem and fills the width of its container.
Component props
The component takes one optional prop:
| Prop | Type | Purpose |
|---|---|---|
context | Record<string, string | number | boolean | null | array> | Page context sent with each message, for example { page: "billing" } |
<EmbeddedAgentPanel context={{ page: "billing" }} />Rules for context:
- Use only keys the binding allows (set in Settings > Embedded agent settings > Page context keys, or from
contextKeysinchipp/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).
Everything else (identity, token handling, styling) is handled for you.
Authentication & identity
The identity mode you chose at install time decides which session route the panel 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 user’s conversations are kept across sessions, and the panel loads previous messages on mount. The panel 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 panel upgrades the session and keeps the conversation. After an SPA login (no page reload), call
notifyEmbeddedAgentSignedIn()fromweb/src/lib/embedded-agent/session-client.ts. See Session upgrading.
If the session cannot be minted (the user is signed out, or the feature is not configured), the panel shows “Chat is not available right now.” instead of failing the page.
Styling & customization
The panel renders natively (no iframe), so it inherits your page’s fonts. Colors and shapes come from --chipp-embed-* CSS variables, which fall back to your design tokens (--primary, --background, --foreground, --border, --radius):
| Variable | Default |
|---|---|
--chipp-embed-accent-color | var(--primary, #4f46e5) |
--chipp-embed-background | var(--background, #ffffff) |
--chipp-embed-foreground | var(--foreground, #111111) |
--chipp-embed-muted | var(--muted-foreground, #6b7280) |
--chipp-embed-border-color | var(--border, #e5e7eb) |
--chipp-embed-radius | var(--radius, 0.5rem) |
--chipp-embed-error-color | #dc2626 |
--chipp-embed-font-family | inherit |
Set any of them on a wrapper element:
.chat-wrapper {
--chipp-embed-accent-color: #0f766e;
--chipp-embed-radius: 0.75rem;
}Voice
Turn voice on with the voice switch in chipp/agent.json ("capabilities": { "voice": true }), then sync the agent. The panel then offers:
- Mic: record a message. The transcript goes into the message box.
- Read aloud: a play button under each reply, and a toggle that reads each new reply aloud. Replies are read in the agent’s selected voice. If you picked a voice under Bring your own voice (ElevenLabs) in the agent’s Voice settings, that voice reads the replies, billed to your own ElevenLabs account. If the selected voice cannot be used (for example your ElevenLabs key ran out of credits), the panel says so. It never swaps in a stock voice.
- Voice mode: a live, two-way voice conversation. The button shows when the agent’s Voice agent is also turned on in Chipp. Voice mode opens an animated voice view with Mute, Transcript and Exit voice mode. You can talk over the agent at any time, and it stops to listen. The conversation continues the open chat thread, so when you exit, everything that was said is in the text chat.
Voice mode runs through Chipp: your app never holds an ElevenLabs or LiveKit key, and usage is billed and limited like every other voice call. If voice mode cannot start (the microphone is blocked, the plan does not include voice, voice is turned off for the agent, or the session fails), the panel shows one sentence and the text chat keeps working.
The panel loads the LiveKit web client for voice mode from a pinned public build. If your app installs livekit-client itself, or its content security policy blocks that host, ask the AI Engineer to pass loadLiveKit: () => import("livekit-client") to the panel.
Errors and retries
If a message fails to send (network, CORS, a 4xx or 5xx, a stream error), the panel marks it “not sent” with an inline error and a Retry button. If history fails to load, the panel shows a banner with Retry.
Troubleshooting
Panel 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 sessionentries. A missingCHIPP_PROJECT_CLIENT_KEYreturns 503; a failed mint returns 502.
Messages not persisting across sessions
- In anonymous mode this is expected: each page load is a new visitor.
- In authenticated mode, conversations are tied to the signed-in user.
Styling does not match my design system
- Set the
--chipp-embed-*variables (see “Styling & customization” above), or define the design tokens they fall back to.
Next steps
- Floating widget: add a floating chat widget
- Backend client: call the agent from your server routes
Ready to build it?
Tell Chipp what you want. Start free, or book a session and build it with our team.