> 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/configuration.md).

# Configuring placements

Create and customise placements for each embeddable agent — where it appears, how it looks, and how it answers.

A **placement** is one configured instance of an embeddable agent: where it appears, what it looks like, and how it answers. You can create several placements for the same agent — for example, one Virtual Try-On tuned for shoes on your shoe pages and another tuned for dresses on your dress pages.

### Navigating to settings

1. Log in to your Alhena AI dashboard.
2. In the sidebar, click **Integrations**.
3. Choose the embeddable agent you want to set up — for example, **Embeddable Virtual Try-On**.
4. Click **Configure settings**.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-e3cdf912b32f1a90f4dbbf7415e10dc4a66ca469%2Fembed-agents-integrations-nav.png?alt=media" alt="" width="563"><figcaption><p><em>Each embeddable agent has its own entry under Integrations.</em></p></figcaption></figure>

***

### The placement list

The first screen shows every placement you've created for that agent.

* **Drag to reorder.** When a shopper loads a page, the agent shows the **first placement whose conditions match** that page, working from the top down. Drag placements to set their priority.
* **Status.** Each placement is **Enabled** or **Disabled**. Disabled placements never show to shoppers.
* **Appears on.** A short summary of the page conditions for each placement.

Click **Create placement** to add a new one, or **Configure settings** on an existing row to edit it.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-55657ab8b2edc01744bc6ff2ec8543ed781e7940%2Fembed-agents-placement-list.png?alt=media" alt="" width="563"><figcaption><p><em>Placements for an agent. The first one whose conditions match the page is the one shoppers see.</em></p></figcaption></figure>

{% hint style="info" %}
A placement with **no conditions** acts as the default — it shows wherever you place the snippet and no other placement matches the page. Keep your most specific placements near the top and a catch-all default at the bottom.
{% endhint %}

***

### The placement editor

Each placement opens in an editor with up to three tabs: **Customize**, **Setup**, and **Playground**.

#### Customize tab

The Customize tab controls everything the shopper sees. The left side is the form, grouped into collapsible sections; the right side is a live **Preview** that updates as you type. Every field is optional — leave one blank and the agent falls back to a sensible default. Which sections you see depends on the agent.

**Placement**

* **Show this placement to shoppers** — the enable/disable switch.
* **Placement name** — an internal label so you can recognise this placement in your list (for example, *"Shoes — collection page"*). Shoppers never see it.
* **How it appears** — **A button that opens a modal** (shoppers tap a button and the agent opens in a panel over the page) or **Embedded in the page** (the agent sits right where you place the snippet, with no button to tap). See [Where the answer appears](/docs/features/embeddable-agents.md#where-the-answer-appears).
* **What opens it** *(Product Reviews, button placements only)* — a **Button**, or a **Card with a preview** showing the rating, summary, and top topics on the page.
* **Kickoff message** *(Product Quiz only)* — the shopper's first message when the quiz opens. Leave blank for the default.

**Button** *(placements that open with a button)*

Styles the launcher button. Size and spacing fields accept any CSS value.

| Setting                     | What it does                                                                 |
| --------------------------- | ---------------------------------------------------------------------------- |
| **Button label**            | The text on the button (for example, *"Try on"*).                            |
| **Show icon on the button** | On by default.                                                               |
| **Button icon**             | Upload a custom icon, or keep the default sparkle.                           |
| **Width**                   | For example, `100%` to fill the space. Leave blank to fit the label.         |
| **Height**                  | For example, `48px`.                                                         |
| **Margin**                  | Space around the button, for example `16px 0`.                               |
| **Font size**               | Pixels, another unit (for example, `1rem`), or a CSS variable. Default 13px. |
| **Font weight**             | 300 to 800.                                                                  |
| **Border color**            | The button outline.                                                          |
| **Background color**        | The button fill. Default white.                                              |
| **Text color**              | The label colour. Default near-black.                                        |
| **Corner radius (px)**      | `0` is square.                                                               |

**Title** (the bar across the top of the panel)

Use these to match your storefront's section headings. Blank fields keep the built-in look.

| Setting                     | What it does                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Title**                   | The heading at the top of the panel.                                                                   |
| **Eyebrow**                 | An optional short line above the title in your accent color (for example, *"Styled by our stylists"*). |
| **Background color**        | The title bar fill.                                                                                    |
| **Text color**              | The title and title-bar icons.                                                                         |
| **Font family**             | A font for the title only. Your website must already load it.                                          |
| **Font size**               | Pixels, another unit (for example, `2rem`), or a CSS variable. Default 15px.                           |
| **Font weight**             | 300 to 900.                                                                                            |
| **Letter spacing (px)**     | Space between letters.                                                                                 |
| **Alignment**               | **Center**, **Left**, or **Right**.                                                                    |
| **Mobile alignment**        | Alignment on screens under 560px wide, or **Same as desktop**.                                         |
| **Text case**               | **As typed**, **UPPERCASE**, **lowercase**, or **Capitalize Each Word**.                               |
| **Padding**                 | CSS padding around the title (for example, `28px 20px`).                                               |
| **Show border under title** | Adds a line under the title bar, with its own **Border color**.                                        |

**Modal** / **Panel** (the container that opens)

Called **Modal** for button placements and **Panel** for embedded ones.

| Setting                                               | What it does                                                                                             |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Background color**                                  | The panel fill.                                                                                          |
| **Accent color**                                      | Your brand colour for buttons, spinners, and opened cards.                                               |
| **Corner radius (px)**                                | Default 16px; `0` for square corners.                                                                    |
| **Margin** *(embedded only)*                          | Space around the panel, for example `48px 0`.                                                            |
| **Alignment** *(embedded only)*                       | **Left**, **Center**, or **Right** within the available space.                                           |
| **Show modal border** / **Show panel border**         | Adds a border, with its own **Border color**.                                                            |
| **Show AI Agent by Alhena AI**                        | The small credit line under the panel.                                                                   |
| **Desktop width** / **Max width**                     | Modal width on desktop (for example, `440px`), or an embedded panel's max width (blank fills the space). |
| **Min height** *(embedded only)*                      | Starting height, for example `400px`.                                                                    |
| **Desktop height** / **Max height**                   | Modal max height, or how tall an embedded panel grows before scrolling inside.                           |
| **Mobile width** and **Mobile height** *(modal only)* | Size on phones. Blank keeps the modal full screen.                                                       |
| **Content padding**                                   | Space inside the panel, for example `18px`.                                                              |
| **Stacking order (z-index)** *(modal only)*           | Layers the modal relative to sticky headers or banners. Blank keeps it on top.                           |
| **Font family**                                       | Defaults to your page's font. Your website must already load any font you set.                           |

{% hint style="info" %}
Text colours, spacing, and font are inherited from your storefront unless you set them.
{% endhint %}

**Cards** *(Outfit Builder and Room Designer only)*

These agents return their result as a set of cards — one per look or room set.

* **Card layout** — choose how the results are laid out:
  * **Standard** — each look (or set) is a card with an image collage and a button that opens its products in a panel below.
  * **Compact** — skips the collage cards and shows the products themselves as a row of small product cards, so shoppers see what's in the look straight away. This suits tighter spots on a product page.
* **Swipe through the products** *(Compact layout only)* — keeps the products in one row that shoppers swipe or scroll sideways. Turn it off and the products wrap onto more rows instead.
* With the **Standard** layout you can also style the cards: border color, corner radius, card width, collage height, and the button's colors both before and while a look is open.

Use the **Preview** to compare the two layouts before you save.

**Expanded look** / **Expanded set** *(Outfit Builder and Room Designer, Standard layout only)*

Styles the panel that opens below the cards:

| Setting                     | What it does                                        |
| --------------------------- | --------------------------------------------------- |
| **Background**              | The panel fill.                                     |
| **Border color**            | The outline of the panel and its close button.      |
| **Corner radius**           | In pixels. Blank follows the cards' corner radius.  |
| **Text color**              | The look's (or set's) title, item count, and total. |
| **Close button background** | The close button fill.                              |

**Photo step** *(Virtual Try-On and See It In Your Room only)*

* **Photo step heading** and **subtext** — the instructions shown on the upload screen (for example, *"Upload a full-body photo"*).
* **Choose-photo button label** — the button that opens the file picker.
* **Photo disclaimer** — the privacy wording shown next to the upload. It's a rich-text field, so you can add **bold**, *italics*, and links — for example, a link to your privacy policy. Whether a consent step is required follows your **Website Chat** settings.

**Waiting** *(agents that produce a result — everything except the Product Quiz and Product Reviews)*

* **Working message** — what the shopper sees while the result is generating (for example, *"Creating your try-on — this can take a minute…"*).

**Result** *(agents that show a one-off result in the panel — not the Product Quiz or Product Reviews)*

* **Try-another button label** *(Virtual Try-On and See It In Your Room)* — lets the shopper try a different photo after seeing the result.
* **Show the "Build personal outfits" button** *(Outfit Builder)* or **Show the "Design personal sets" button** *(Room Designer)* — a button under the result that opens your chat widget, where the shopper gets a version built around their own preferences. On by default; turn it off to keep shoppers in the panel.
* **Show thumbs up and down** — lets the shopper say whether the result was helpful. The vote is saved on that reply in the conversation. On by default; turn it off for a cleaner result.

**Reviews content** *(Product Reviews only)*

* **Show rating and review count** — the star rating and how many reviews it's based on, above the summary.
* **Visible topics in overview** — 2, 3, or 4 topic chips; the rest sit behind "+N more".
* **Summary lines** *(Embedded in the page only)* — 2 to 5 lines before a **Show more** link.
* **Static-only mode** — hides the suggested questions and ask box.

The summary and topics are generated from your reviews and aren't editable.

**Preview states**

The Preview on the right has buttons that step through what a shopper sees at each stage, such as **Button**, **Photo**, **Ready**, **Waiting**, and **Result** (Product Reviews uses **Launcher**, **Overview**, **Topic**, and **Empty**). The states depend on the agent and how it appears.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-396f3c350c84ba1d647649e8e56d38b00ea47ce9%2Fembed-agents-style-tab.png?alt=media" alt="Placement editor Customize tab with collapsible Placement, Button, Title, Modal and Quiz sections and a live Preview" width="563"><figcaption><p><em>The Customize tab for a Product Quiz placement. Each section collapses, and the Preview on the right steps through each state.</em></p></figcaption></figure>

#### Setup tab

The Setup tab controls **where** the placement appears and how it's installed.

**Where it appears**

Click **Add condition** to limit this placement to specific pages. Each condition can match by:

* **Page URL** — *Contains at least one of*, *Doesn't contain*, *Is*, or *Is not*. Enter one or more values, one per line. Check **Ignore URL parameters (everything after ?)** to match the page whatever comes after the `?` in its address.
* **Page title** — the same operators, matched against the page's title.

All conditions must match for the placement to show. With no conditions, the placement is the default for that agent (shown wherever the snippet is placed and no higher placement matches).

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-35f29238929a3137e8b2842a765d862bc72765b1%2Fembed-agents-setup-conditions.png?alt=media" alt="" width="563"><figcaption><p><em>Conditions decide which pages a placement appears on.</em></p></figcaption></figure>

**Auto-insert** and **Manual Installation** — putting the agent on your website. See [Installation](/docs/features/embeddable-agents/installation.md).

#### Playground tab

The Playground is a live test bench — run the **real** agent on a page before you publish, without installing anything on your site.

1. Pick a **Language**.
2. Pick a **Product** (for Virtual Try-On, Outfit Builder, See It In Your Room, and Room Designer) or a **Page URL** (for the Product Quiz and Product Reviews).
3. Use the panel exactly as a shopper would — upload a photo, generate a try-on, or take the quiz.

Every time you change the language or product, the Playground starts a fresh session, so you can re-test cleanly.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-b2839f629caf8d107a2f955f1d05554bc00c655c%2Fembed-agents-playground.png?alt=media" alt="" width="563"><figcaption><p><em>The Playground runs the real agent so you can test before publishing.</em></p></figcaption></figure>

***

### Saving

Click **Save changes** (or **Create placement** for a new one) to publish. Changes go live within a few minutes. To remove a placement, open it and click **Delete placement**.

Next: [add the agent to your website →](/docs/features/embeddable-agents/installation.md)