> 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

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 **Install** 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>`   |

<figure><img src="/files/Cvop7V9a641aWMB94uUw" alt="" width="563"><figcaption><p><em>The Install 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 %}

***

### 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="/files/0LscN722mGCphT9H3TCB" 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.

***

### 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 panel is full-width on mobile regardless of the desktop width you set.

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