Configuration

How configuration works

The Concierge has two configuration sources:

HTML attributes you set on the tag — everything listed on this page.
Runtime configuration from the Bonsai dashboard — brand colors, fetched per-tenant at load time using your api-key and applied automatically as CSS custom properties.

Precedence

For any given value, the component resolves in this order:

Inline CSS custom property set on the tag’s style attribute
Dashboard configuration for this api-key
Built-in default

Inline styles are re-applied after the dashboard response arrives, so a value you pin on the tag is never overwritten by a later dashboard change. HTML attributes listed below have no dashboard equivalent — they are read only from the DOM.

Components

Tag	Purpose
`<bonsai-chat-bubble>`	Floating launcher button plus the chat panel it opens. The usual embed.
`<bonsai-chat>`	Opens the chat panel immediately on page load, with no launcher button.
`<bonsai-question-marquee>`	A scrolling strip of AI-generated questions about the product in context. Clicking one opens the chat on that question.

<bonsai-chat> opens on load — it does not render in place. It is not an inline chat you can position in your layout; it is the same overlay panel, opened automatically. Use it only where you want the conversation to start unprompted. For a launcher the shopper chooses to press, use <bonsai-chat-bubble>.<bonsai-question-marquee> additionally requires external-id (or sku) and renders nothing if the product has no generated questions.

Required attributes

required

Your Bonsai API key. Required on every component. Used to fetch runtime configuration and to authenticate the conversation.

<bonsai-chat-bubble api-key="YOUR_API_KEY_HERE"></bonsai-chat-bubble>

Connection

Attribute	Required	Default	Notes
`api-key`	Yes	—	Your Bonsai API key
`base-url`	No	`https://agent.hibonsai.com`	Agent API base URL. When omitted, it is derived from the origin of the loaded `bonsai-agent` script, falling back to the default

Only set this if you are pointing an embed at a non-production environment. In normal installations, leave it off — the component infers it from the script tag it was loaded from.

Launcher appearance

These apply to <bonsai-chat-bubble> only.

Attribute	Required	Default	Notes
`label`	No	`"Ask"`	Visible text on the launcher. Also used as its accessible name unless `launcher-aria-label` is set
`launcher-variant`	No	`pill`	`pill` (rounded, floating) or `tab` (flush against the viewport edge). `edge-tab` is accepted as a synonym for `tab`
`launcher-content`	No	`text`	`text`, `text-icon`, or `icon`
`launcher-side`	No	`right`	`left` or `right`
`launcher-icon`	No	`mark`	Built-in glyph: `mark` (Bonsai mark), `sparkles`, or `chat`
`launcher-icon-url`	No	—	URL of your own icon image. Falls back to the built-in `launcher-icon` if the image fails to load
`launcher-aria-label`	No	—	Explicit accessible name. Required in practice when `launcher-content="icon"`, since there is no visible text
`icon-only`	No	`false`	Legacy. Boolean equivalent to `launcher-content="icon"` with the `chat` glyph. Prefer `launcher-content`

An unrecognized value falls back to the default rather than erroring. launcher-variant="rounded" renders a pill; launcher-icon="star" renders the Bonsai mark. Values are matched case-insensitively and trimmed, so " TAB " resolves to tab.

When launcher-content is text or text-icon, this is only honored if it contains the visible label — otherwise the visible label is used instead, so that a shopper using voice control can say what they see.

<bonsai-chat-bubble
  api-key="API-KEY"
  launcher-content="icon"
  launcher-aria-label="Open the shopping assistant"
></bonsai-chat-bubble>

Launcher position

Attribute	Required	Default	Notes
`bubble-bottom`	No	`20px`	Distance from the bottom of the viewport
`bubble-right`	No	`20px`	Distance from the right edge. Applies when `launcher-side="right"`
`bubble-left`	No	`20px`	Distance from the left edge. Applies when `launcher-side="left"`
`bubble-top`	No	`50%`	Vertical position. Applies to the `tab` variant, which is centered on the edge rather than sitting at the bottom

Each of these sets the corresponding CSS custom property, so anything valid in CSS works — 82px, 4rem, calc(20px + env(safe-area-inset-bottom)).

Panel content

These apply to <bonsai-chat-bubble> and <bonsai-chat>.

Attribute	Required	Default	Notes
`title`	No	—	Heading shown in the panel header
`header-icon-url`	No	—	Logo shown in the panel header. Not used for the launcher icon
`header-layout`	No	—	Header arrangement
`welcome-title`	No	—	Heading of the opening message
`welcome-message`	No	—	Body of the opening message
`placeholder`	No	—	Composer input placeholder
`assistant-label`	No	—	Name shown against assistant replies
`disclaimer-statement`	No	—	Fine print shown beneath the composer
`theme`	No	`light`	`light` or `dark`. Any other value resolves to `light`

Behavior

Attribute	Required	Default	Notes
`auto-open`	No	`false`	Boolean. Opens the panel immediately on page load
`idle-open`	No	—	Number of seconds of shopper inactivity after which the panel opens by itself. Omit to never auto-open on idle
`mobile-expanded`	No	`false`	Boolean. On phone-sized viewports, present the panel as a full-height sheet
`clear-on-close`	No	`false`	Boolean. Discard the conversation when the panel is closed, so the next open starts fresh
`disable-input`	No	`false`	Boolean. Render the conversation read-only
`disable-search-refine`	No	`false`	Boolean. Stop the Concierge from reacting to on-site search queries
`handoff`	No	`false`	Boolean. Enable the support handoff affordance — see Events & API
`external-id`	No	—	Identifier for the product or entity in context on this page
`sku`	No	—	Alias for `external-id`, read only when `external-id` is absent

The timer resets on any pointer move, pointer press, key press, scroll, or touch, and pauses while the tab is hidden — so a shopper who leaves a tab open in the background does not return to an opened panel. It fires at most once, and never while the panel is already open.

<bonsai-chat-bubble api-key="API-KEY" idle-open="30"></bonsai-chat-bubble>

Set this on product pages so the conversation knows which product the shopper is looking at.

<bonsai-chat-bubble
  api-key="API-KEY"
  external-id="{{ product.id }}"
></bonsai-chat-bubble>

Sales call-to-action

An optional promotional row rendered inside the panel after a set number of exchanges.

Attribute	Required	Default	Notes
`sales-cta`	No	—	The call-to-action text
`sales-cta-href`	No	—	Destination URL
`sales-cta-label`	No	—	Text on the action button
`sales-cta-after`	No	`5`	Number of messages before it appears. A non-numeric or non-positive value falls back to `5`

Boolean attributes

Every attribute marked Boolean above is presence-based, following the HTML convention. The attribute being present enables it, whatever its value:

<!-- All three of these ENABLE the behavior -->
<bonsai-chat-bubble handoff></bonsai-chat-bubble>
<bonsai-chat-bubble handoff=""></bonsai-chat-bubble>
<bonsai-chat-bubble handoff="false"></bonsai-chat-bubble>

<!-- To disable it, omit the attribute entirely -->
<bonsai-chat-bubble></bonsai-chat-bubble>

handoff="false" enables handoff. This trips people up — if you are toggling one of these from a template, omit the attribute rather than setting it to a falsy string.

Get Started

Web Components

Support

How configuration works

Precedence

Components

Required attributes

Connection

Launcher appearance

Launcher position

Panel content

Behavior

Sales call-to-action

Boolean attributes

​How configuration works

​Precedence

​Components

​Required attributes

​Connection

​Launcher appearance

​Launcher position

​Panel content

​Behavior

​Sales call-to-action

​Boolean attributes

How configuration works

Precedence

Components

Required attributes

Connection

Launcher appearance

Launcher position

Panel content

Behavior

Sales call-to-action

Boolean attributes