Skip to main content

​
Getting Started

Before getting started, ensure that you’ve had a chance to review the Quickstart prerequisites. The Concierge is a conversational shopping assistant. It adds a floating launcher button to your storefront; opening it slides in a chat panel where shoppers can ask questions in natural language and get answers grounded in your catalog.
If you want a search box or a full search results page rather than a conversation,
use the Bonsai Search Bar or Bonsai Search instead.

​
Quick Installation

Use this minimal 2-step setup to render the Concierge on your website.
Theming is managed in the Bonsai dashboard. When the component loads, it fetches your tenant’s brand colors using your api-key and applies them automatically. You can override any value per-embed with CSS custom properties set inline on the element — see Advanced Styling.
1

Install the script

Add the Concierge <script> tag to your HTML page. Place this in the <head> section, or before the closing </body> tag.
The -latest alias always serves the current release. To pin a specific version instead, replace latest with the version number — for example bonsai-agent-0.22.0.js.
2

Add the component

Add <bonsai-chat-bubble> anywhere in the <body>. The launcher positions itself as a fixed overlay, so its position in the DOM does not matter.Only api-key is required.
3

Test the Concierge with a question

Click the launcher and ask something a shopper would ask. Not working? Check the Troubleshooting guide for common issues.

​
Placement on your site

The Concierge is designed to be present on every page, not just a search page. Add the tag once in your theme layout so shoppers can open it from anywhere. The launcher is fixed to the bottom-right corner by default. If it collides with an existing element — a cookie banner, a live-chat widget, a sticky add-to-cart bar — move it rather than hiding it:

​
Choosing a launcher style

The launcher has three independent settings: its shape (launcher-variant), what it shows (launcher-content), and which side it anchors to (launcher-side).
Set launcher-icon-url if you want your own glyph. On phones 380px and narrower the launcher hides its text label and shows only its icon. Without launcher-icon-url, that icon is the built-in Bonsai mark, so your storefront will show our glyph rather than yours at that width. header-icon-url is a different attribute — it supplies the logo inside the opened panel and is not reused for the launcher. See Responsive behavior.

​
Opening the chat from your own UI

To open the Concierge from an existing button, a nav link, or an empty-search-results state, dispatch a bonsai:open-chat event on window. It reuses the configuration already on your <bonsai-chat-bubble> tag, so you do not repeat your API key:
You can seed the conversation with a question by passing it in the event detail:
This requires a <bonsai-chat-bubble> on the page — it is what supplies the configuration. See Events & API for the full surface.

​
Next Steps

Configuration

Full attribute reference and default values for the Concierge component.

Advanced Styling

CSS variable reference, launcher tokens, and responsive behavior.

Events & API

The window.BonsaiAgent global and the support handoff event.

Troubleshooting

Common integration issues and how to resolve them.