Configuration

The <scentbot-widget> element is configured through HTML attributes. All attribute names use kebab-case.

Required attributes

Attribute	Type	Description
`public-key`	`string`	API key provided by ScentXP. Required for widget initialization.

Optional attributes

Language and user identity

Attribute	Type	Default	Description
`language`	`string`	`"en"`	ISO 639-1 language code (e.g., `"en"`, `"fr"`, `"ar"`). Arabic (`ar`) enables right-to-left layout.
`user-id`	`string`	`""`	Identifier for the logged-in user. Used to associate conversations with a specific customer.
`metadata`	JSON string	`"{}"`	Stringified JSON object with user context. See Metadata below.

Positioning and notifications

Attribute	Type	Default	Description
`position`	`string`	`"bottom-right"`	Widget placement. Options: `bottom-right`, `bottom-left`, `bottom-center`, `center`, `none`, `fill-container`.
`notifications`	`string`	—	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` event.

Appearance and customization

Attribute	Type	Default	Description
`styles`	URL string	—	URL to a custom CSS file loaded during widget initialization. Use this to override default styles.
`custom-css`	URL string	—	Alias for `styles`.
`loading-type`	`string`	`"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).
`disable`	JSON string	`"{}"`	Stringified JSON object to disable specific UI features. See Disable options below.

Session

Attribute	Type	Default	Description
`chat-history-expiration-hours`	`number`	`12`	Hours to keep conversation history in the browser. After this period with no user interaction, the conversation resets.

Metadata

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
`brand`	`string`	Brand context for scoping the conversation
`families`	`string[]`	Preferred fragrance families
`free_field`	`string`	Free-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
`closeButton`	Hide the close button
`refreshButton`	Hide the refresh/reset conversation button
`header`	Hide the widget header
`headerAnimation`	Disable header animation
`openAnimation`	Disable open/close animation
`closeAnimation`	Disable close animation
`perfumeInfo`	Hide perfume detail information
`perfumeBuy`	Hide the buy button on perfume cards
`perfumePrice`	Hide price information on perfume cards
`chatbox`	Hide the chat input box
`background`	Disable the backdrop overlay
`zIndex`	Disable z-index styling (useful for custom stacking contexts)

Position modes

Value	Behavior
`bottom-right`	Floating button and panel anchored to the bottom-right corner (default)
`bottom-left`	Floating button and panel anchored to the bottom-left corner
`bottom-center`	Floating button and panel centered at the bottom
`center`	Centered on the viewport
`fill-container`	Fills the parent container; widget is always open
`none`	No 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>

Widget attributes

Required attributes

Optional attributes

Language and user identity

Positioning and notifications

Open/close behavior

Appearance and customization

Session

Metadata

Disable options

Position modes

Example: fully configured widget

Next steps

Events

Capabilities

​Widget attributes

​Required attributes

​Optional attributes

​Language and user identity

​Positioning and notifications

​Open/close behavior

​Appearance and customization

​Session

​Metadata

​Disable options

​Position modes

​Example: fully configured widget

​Next steps

Events

Capabilities

Widget attributes

Required attributes

Optional attributes

Language and user identity

Positioning and notifications

Open/close behavior

Appearance and customization

Session

Metadata

Disable options

Position modes

Example: fully configured widget

Next steps