Configuration

Customize widget appearance and behavior

Branding Settings

The widget automatically inherits your agent’s branding. Configure these in Branding → Design and Content tabs:

Setting	Where	Widget Effect
Accent Color	Design tab	Bubble background color
Background Color	Design tab	Frame border/shadow tinting
Theme	Design tab	Light/dark tooltip styling
Bot Avatar	Agent settings	Bubble icon
Message Greetings	Content tab	Stacked greeting bubbles above the button
Conversation Starters	Content tab	Quick-action buttons in the chat
Input Placeholder	Content tab	Chat input hint text

Widget-Specific Settings

These are configured in Branding → Design tab under the Chat Widget section:

Position

Choose where the bubble appears on the page:

• Bottom Right (default)
• Bottom Left

Auto Open

Automatically open the widget after a delay when the page loads.

• Enable/Disable toggle
• Delay — seconds before the widget opens (1–60, default 5)

Open Style

Choose how the chat opens when a visitor clicks the bubble:

• Normal — opens the current floating chat window.
• Sidepanel — opens a full-height docked panel from the left or right side of the page.
• Agent dock — shows a centered input-style launcher at the bottom of the page and expands into a wider chat panel.

Sidepanel mode is useful when the agent should stay visible while the visitor continues reading the page, comparing plans, reviewing media, or working through a guided flow.

Agent dock mode is useful when the widget should feel closer to the hosted agent experience: always visible as a prompt bar, less interruptive than a bubble, and strong for marketing pages that invite visitors to ask a question directly.

The default desktop dock width is 720px. You can change it in Branding → Chat Widget or by passing data-dock-width / dockWidth in the embed setup.

Sidepanel Page Push

When Push page content is enabled, BoostGPT docks the root html element and reserves space for the sidepanel. The default desktop panel width is 400px.

The widget exposes these CSS variables while docked:

Variable	Purpose
--bgpt-docked-width	Current sidepanel width
--bgpt-docked-viewport-offset	Reserved page space for the sidepanel
--bgpt-docked-viewport-width	Remaining viewport width for the page

Most page content moves automatically. Fixed, sticky, or absolutely positioned page chrome may need an explicit marker because those elements often sit outside normal document flow:

<header data-boostgpt-push class="fixed inset-x-0 top-0">
  ...
</header>

BoostGPT does not automatically push every header, nav, .fixed, or .sticky element because broad auto-detection can move unrelated UI. Add data-boostgpt-push only to the fixed elements that should stay aligned with the pushed page.

Presentation Mode

Presentation mode lets clicked media and files open in the page area beside the sidepanel. This is useful when an agent needs to show a proposal image, product video, generated page, workspace file preview, or document without sending the visitor away from the conversation.

Supported click paths include:

• Markdown images and media links
• Uploaded attachment cards
• Tool-generated images, videos, audio, files, and HTML previews
• Workspace and Artifactuse previews

Guided Page Actions

Agents can guide visitors through the page when the widget is embedded in sidepanel mode. Safe actions include scrolling to a section, highlighting an element, focusing a field, suggesting a click, and opening media in presentation mode.

For reliable guided flows, define named page actions in your embed setup:

boostgpt.init({
  botId: 'YOUR_BOT_UUID',
  openStyle: 'sidepanel',
  pageActions: {
    pricing: { selector: '#pricing', label: 'Pricing' },
    demo: { selector: '[data-boostgpt-action="schedule-demo"]', label: 'Schedule demo' },
  },
});

You can also configure these targets from the agent’s Branding → Chat Widget settings. Stored targets are returned by the widget config endpoint, so your embed snippet can stay simple.

The agent can use these targets to guide the visitor without submitting forms or performing destructive actions on their behalf.

The widget also exposes boostgpt.getPageContext() for debugging. It returns the safe visible page context the agent can request before a walkthrough: title, URL, headings, nav links, sections, CTAs, and configured page action IDs.

Greeting Bubbles

The widget shows your Message Greetings (from Content tab) as stacked chat bubbles above the floating button. Each greeting appears as a separate message card.

Clicking any greeting bubble opens the widget.

To configure greetings:

1. Go to Branding → Content tab
2. Enable Message Greetings
3. Add 1–4 greeting messages

If greetings are disabled, only the floating bubble button is shown.

Passing Context

You can pass metadata from your website to the agent conversation:

boostgpt.init({
  botId: 'YOUR_BOT_UUID',
  metadata: {
    page: 'pricing',
    plan: 'pro',
    userId: '12345',
  },
});

Metadata is available to the agent as conversation context, allowing it to personalize responses based on what page the user is on or what product they’re viewing.

Mobile Behavior

On screens narrower than 480px, the widget iframe expands to full-screen when opened, providing a native app-like experience.