> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scentxp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

## Custom events

ScentBot communicates with your application through browser [Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). Use these events to integrate with your cart, analytics, or UI state.

All events are dispatched on the `window` object.

## Events emitted by ScentBot

Listen for these events to react to user actions inside the widget.

### `sxp.scentbot.ready`

Fired when the widget has finished initializing and is ready for interaction.

```javascript theme={null}
window.addEventListener("sxp.scentbot.ready", () => {
  console.log("ScentBot is ready");
});
```

### `sxp.scentbot.addToCart`

Fired when a user clicks the buy button on a perfume card and no direct purchase URL is available. Use this to add the product to your cart programmatically.

```javascript theme={null}
window.addEventListener("sxp.scentbot.addToCart", (event) => {
  const { id, ean } = event.detail;
  // Add product to your cart using EAN or internal ID
  addToCart(ean);
});
```

**Event detail:**

| Property     | Type  | Description                                |
| ------------ | ----- | ------------------------------------------ |
| `id`         | `any` | WikiParfum perfume ID                      |
| `ean`        | `any` | Product EAN (barcode)                      |
| `internalId` | `any` | Internal product identifier (if available) |

### `sxp.scentbot.exit`

Fired when the user closes the widget.

```javascript theme={null}
window.addEventListener("sxp.scentbot.exit", () => {
  console.log("User closed ScentBot");
});
```

***

## Control ScentBot

Dispatch these events to control the widget from your application code.

### `sxp.scentbot.set`

Update the widget state programmatically. The most common use case is opening or closing the widget:

```javascript theme={null}
// Open the widget
window.dispatchEvent(new CustomEvent("sxp.scentbot.set", {
  detail: { open: true }
}));

// Close the widget
window.dispatchEvent(new CustomEvent("sxp.scentbot.set", {
  detail: { open: false }
}));
```

This event is particularly useful when the widget is in [controlled mode](/scentbot/configuration) (`controlled="true"`), where the open/close state is fully managed by your application.

***

## Cart integration example

A typical integration listens for `addToCart`, adds the item to the cart, and notifies ScentBot of the result:

```javascript theme={null}
window.addEventListener("sxp.scentbot.addToCart", async (event) => {
  const { ean, id } = event.detail;

  try {
    await yourCartApi.addItem({ ean });

    // Notify ScentBot the item was added successfully
    window.dispatchEvent(new CustomEvent("sxp.scentbot.addedToCart", {
      detail: { ean, id }
    }));
  } catch (error) {
    // Notify ScentBot the add-to-cart failed
    window.dispatchEvent(new CustomEvent("sxp.scentbot.addedToCartError", {
      detail: { ean, id, error: error.message }
    }));
  }
});
```

**Feedback events:**

| Event                           | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `sxp.scentbot.addedToCart`      | Dispatch to confirm the item was added to the cart |
| `sxp.scentbot.addedToCartError` | Dispatch to notify that the cart operation failed  |

ScentBot uses these feedback events to display appropriate success or error messages to the user.

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/scentbot/configuration">
    All widget attributes for customizing behavior and appearance.
  </Card>

  <Card title="Capabilities" icon="wand-magic-sparkles" href="/scentbot/capabilities">
    Search types, image search, multi-language, and session persistence.
  </Card>
</CardGroup>