> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/features/embeddable-agents/installation.md).

# Installation

Add an embeddable agent to your website with a small HTML snippet.

You add an embeddable agent to your store by pasting one small snippet where you want the button to appear. The snippet is the same for every page — the right placement is chosen automatically from the [conditions](/docs/features/embeddable-agents/configuration.md#setup-tab) you set.

### Prerequisites

* The **Alhena chat widget (SDK)** must be installed on your site. Embeddable agents are rendered by the same script. If you've already added the chat widget, nothing else is needed — see the [chat widget Installation](/docs/features/chat-widget/installation.md) page if you haven't.

***

### Add the snippet

On the placement's **Setup** tab, the **Manual Installation** section shows a ready-to-copy snippet:

```html
<div data-alhena-embed="VIRTUAL_TRY_ON"></div>
```

Paste it into your page's HTML wherever you want the agent's button to appear — for example, just under the **Add to cart** button on your product template.

Each agent has its own value for `data-alhena-embed`:

| Agent               | Snippet                                            |
| ------------------- | -------------------------------------------------- |
| Virtual Try-On      | `<div data-alhena-embed="VIRTUAL_TRY_ON"></div>`   |
| See It In Your Room | `<div data-alhena-embed="SEE_IN_YOUR_ROOM"></div>` |
| Outfit Builder      | `<div data-alhena-embed="OUTFIT_BUILDER"></div>`   |
| Room Designer       | `<div data-alhena-embed="ROOM_DESIGNER"></div>`    |
| Product Quiz        | `<div data-alhena-embed="PRODUCT_EXPERT"></div>`   |
| Product Reviews     | `<div data-alhena-embed="PRODUCT_REVIEWS"></div>`  |

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-800690e77e54b1f1da0643f2b2c2b7a877b1cc0b%2Fembed-agents-setup-install.png?alt=media" alt="" width="563"><figcaption><p><em>The Manual Installation section gives you a copy-ready snippet. Use "Copy Code" or "Email Code to Team Member" to send it to whoever manages your site.</em></p></figcaption></figure>

{% hint style="info" %}
**One snippet, many placements.** You only ever paste one snippet per agent. The panel looks at the page the shopper is on and shows the first matching placement based on the conditions you set — so you can run different placements on different pages without changing the snippet.
{% endhint %}

#### Show the button while the page loads

By default the button appears once the Alhena widget loads. To show it as soon as the page appears:

1. On the **Setup** tab, under **Manual Installation**, turn on **Show the button while the page loads**.
2. Copy the snippet, which now includes a styled copy of the button, and paste it in place of the short snippet.

{% hint style="warning" %}
The copied button doesn't follow later edits. If you change the button on the **Customize** tab, copy and paste the snippet again.
{% endhint %}

***

### Auto-insert (no code)

If you'd rather not edit your page's HTML, turn on **Auto-insert** on the **Setup** tab. Instead of pasting the snippet, Alhena injects the panel automatically next to an element you choose.

1. Toggle on **Auto-insert**.
2. Enter a **CSS selector** for the element to anchor to (for example, `.product-form__buttons`).
3. Choose a **Position**:
   * **Insert before** — immediately before the element.
   * **Insert after** — immediately after the element.
   * **Append inside** — inside the element, at the end.

Auto-insert respects the same page conditions as the snippet, so the agent still only appears where you want it.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-6ddecde6147c480b28fc1d23a79a16192bb2cbe2%2Fembed-agents-setup-autoinsert.png?alt=media" alt="" width="563"><figcaption><p><em>Auto-insert places the panel at a CSS selector without editing your HTML.</em></p></figcaption></figure>

***

### Single-page (SPA) stores

On most sites the snippet works as-is. On a single-page storefront — where navigating to a new product doesn't reload the page — call this after the new page renders so the agent mounts on the new container:

```javascript
window.gleenWidget.initializeEmbeddedAgents();
```

This is already part of the Alhena widget script; you just need to call it after a route change.

***

### Opening an agent from your own button

If you'd rather open an agent from a button or link you already have on your site — instead of the agent's built-in launcher — your developer can do it with one line. No snippet is needed on the page for this:

```javascript
window.gleenWidget.launchEmbeddable('VIRTUAL_TRY_ON');
```

Use the same agent value as in the snippet table above (`VIRTUAL_TRY_ON`, `SEE_IN_YOUR_ROOM`, `OUTFIT_BUILDER`, `ROOM_DESIGNER`, `PRODUCT_EXPERT`, or `PRODUCT_REVIEWS`). The agent opens in a modal, recognises the product from the page, and uses the same placement conditions as the snippet — so it only appears on pages where you've enabled a placement. To pin it to a specific placement, pass its slug:

```javascript
window.gleenWidget.launchEmbeddable('ROOM_DESIGNER', { instance: 'living-room-designer' });
```

For the Product Quiz, you can also pass along the shopper's question — for example from a search box — and the quiz answers it straight away:

```javascript
window.gleenWidget.sendQuizMessage('Which running shoe is best for flat feet?');
```

If the shopper is already partway through a quiz, this reopens their conversation where they left off rather than asking the new question. Your developer can change that so the question starts a fresh quiz or is added to the current one.

See [`launchEmbeddable`](/docs/developer-reference/website-sdk/javascript-api.md#launchembeddable-agentkey-options) and [`sendQuizMessage`](/docs/developer-reference/website-sdk/javascript-api.md#sendquizmessage-message-options) in the Website SDK reference for the full details.

***

### Advanced: overriding a placement from the page

For most stores the dashboard placement settings are all you need. If you want a developer to override a few values directly on the page, the container accepts optional attributes:

```html
<div
  data-alhena-embed="VIRTUAL_TRY_ON"
  data-instance="shoes-collection"
  data-title="Try these on"
  data-subtitle="See how they look on you"
  data-cta-label="Try on"
  data-accent-color="#1a1a1a"
></div>
```

* `data-instance` — pin this container to a specific placement by its slug, instead of resolving one by page URL.
* `data-title`, `data-subtitle`, `data-cta-label`, `data-accent-color` — override the corresponding placement settings for this container only.

***

### Behavior notes

* **No product wiring.** The agent recognises which product the shopper is viewing from the page itself — you don't pass product IDs or data.
* **Never breaks the page.** If no placement matches and there's no default, the panel simply doesn't render; your page is unaffected.
* **Mobile-friendly.** The modal opens full screen on phones unless you set a **Mobile width** or **Mobile height**.

For further assistance, use the **AI Help** button in your Alhena AI dashboard.