The <scentbot-widget> element is configured through HTML attributes. All attribute names use kebab-case.
Required attributes Attribute Type Description public-keystringAPI key provided by ScentXP. Required for widget initialization.
Optional attributes Language and user identity Attribute Type Default Description languagestring"en"ISO 639-1 language code (e.g., "en", "fr", "ar"). Arabic (ar) enables right-to-left layout. user-idstring""Identifier for the logged-in user. Used to associate conversations with a specific customer. metadataJSON string "{}"Stringified JSON object with user context. See Metadata below.
Positioning and notifications Attribute Type Default Description positionstring"bottom-right"Widget placement. Options: bottom-right, bottom-left, bottom-center, center, none, fill-container. notificationsstring— Notification style when the widget is closed and receives a message. Options: popup, text, number.
Open/close behavior Attribute Type Default Description default-open"true" | "false"— Initial state on first page load. Overrides remembered state from previous sessions. open"true" | "false"— Explicitly controls the widget’s open/closed state. When set, overrides user interaction. controlled"true" | "false""false"When "true", the widget’s open/close state is fully managed externally via the sxp.scentbot.set
Appearance and customization Attribute Type Default Description stylesURL string — URL to a custom CSS file loaded during widget initialization. Use this to override default styles. custom-cssURL string — Alias for styles. loading-typestring"default"Loading indicator type. Options: default (placeholder content), spinner (animated spinner). buy-info"true" | "false"— Show buy button and price information on perfume cards (when available in your catalog). disableJSON string "{}"Stringified JSON object to disable specific UI features. See Disable options below.
Session Attribute Type Default Description chat-history-expiration-hoursnumber12Hours to keep conversation history in the browser. After this period with no user interaction, the conversation resets.
The metadata attribute accepts a stringified JSON object with user context that helps ScentBot personalize recommendations:
< scentbot-widget public-key = "your_key" language = "en" metadata = '{"brand":"Dior","families":["floral","fresh"],"free_field":"prefers light scents"}' ></ scentbot-widget >
Field Type Description brandstringBrand context for scoping the conversation familiesstring[]Preferred fragrance families free_fieldstringFree-text context passed to the conversation
Additional custom fields can be included and will be forwarded to the backend.
Disable options The disable attribute accepts a stringified JSON object. Set any property to true to disable that feature:
< scentbot-widget public-key = "your_key" language = "en" disable = '{"closeButton":true,"headerAnimation":true}' ></ scentbot-widget >
Property Description closeButtonHide the close button refreshButtonHide the refresh/reset conversation button headerHide the widget header headerAnimationDisable header animation openAnimationDisable open/close animation closeAnimationDisable close animation perfumeInfoHide perfume detail information perfumeBuyHide the buy button on perfume cards perfumePriceHide price information on perfume cards chatboxHide the chat input box backgroundDisable the backdrop overlay zIndexDisable z-index styling (useful for custom stacking contexts)
Position modes Value Behavior bottom-rightFloating button and panel anchored to the bottom-right corner (default) bottom-leftFloating button and panel anchored to the bottom-left corner bottom-centerFloating button and panel centered at the bottom centerCentered on the viewport fill-containerFills the parent container; widget is always open noneNo positioning styles applied; you control placement with your own CSS
When using fill-container, the widget opens automatically and fills its parent element. This is useful for embedding ScentBot in a dedicated page section rather than as a floating overlay.
< scentbot-widget public-key = "pk_live_abc123" language = "fr" user-id = "user_42" position = "bottom-right" notifications = "popup" buy-info = "true" chat-history-expiration-hours = "24" metadata = '{"brand":"Chanel","families":["oriental","woody"]}' disable = '{"refreshButton":true}' ></ scentbot-widget >
Next steps
Events Listen for add-to-cart events and control the widget programmatically.
Capabilities What ScentBot can do — search types, image search, and more.
