Skip to main content

​
How configuration works

The Concierge has two configuration sources:
  1. HTML attributes you set on the tag — everything listed on this page.
  2. 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:
  1. Inline CSS custom property set on the tag’s style attribute
  2. Dashboard configuration for this api-key
  3. 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

<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.

​
Connection

​
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.
An unrecognized value falls back to the default rather than erroring. launcher-variant="rounded" renders a pill; launcher-icon="star" renders the sparkles glyph. Values are matched case-insensitively and trimmed, so " TAB " resolves to tab.
​
On phones 380px and narrower the launcher shrinks to a compact tab and shows this text instead of label. If you do not set it:
  1. label is reused when it is 10 characters or shorter
  2. Otherwise it falls back to "Ask AI"
So label="Ask" needs nothing, and label="Ask us anything" renders Ask AI on a small phone unless you supply something better.
Keep it to roughly 10 characters — the compact tab is narrow, and longer text is truncated with an ellipsis rather than wrapped. See Responsive behavior.
​
When launcher-content is text or text-icon, this is only honored if it contains both the visible label and the compact label — otherwise the rendered text is used as the accessible name instead, so that a shopper using voice control can always say what they see.

​
Launcher position

Each of these sets the corresponding CSS custom property, so anything valid in CSS works — 82px, 4rem, calc(20px + env(safe-area-inset-bottom)).
These do not apply on phones 380px and narrower. At that width every launcher becomes a compact tab pinned to the side of the viewport and centered vertically, so bubble-bottom, bubble-right, bubble-left, and bubble-top are all ignored. To move it there, set --bonsai-agent-bubble-compact-top — see Responsive behavior.

​
Panel content

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

​
Behavior

​
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.
​
Set this on product pages so the conversation knows which product the shopper is looking at.

​
Sales call-to-action

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

​
Boolean attributes

Every attribute marked Boolean above is presence-based, following the HTML convention. The attribute being present enables it, whatever its value:
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.