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

# Embedded Chat

> Show the homie assistant as its own page in your shop: your navigation stays on top, the chat fills the page content below.

With the embedded chat, the assistant becomes a page of your shop instead of a floating widget. Your shop keeps its own navigation bar and back or close button, and the chat sits as a centered column in the page content below. Shoppers see the same conversation as in the widget on your other pages.

> [!NOTE]
>
> Before you start, make sure you have: - The homie embed script installed on your site (see
> [Manual](https://docs.yourhomie.ai/en/user-guide/installation/manual.md)) - A page in your shop that should show the assistant, for example
> `/assistant`

## Add the embedded chat to a page

**1. Add the container**

Add an empty element with the ID `homie-embedded-chat` where the chat should appear, below your navigation bar. The ID is fixed and cannot be changed. Leave the element empty: content inside it is not shown.

```html assistant.html theme={null}
<div id="homie-embedded-chat" style="height: calc(100dvh - 64px);"></div>
```

The chat fills the container completely. **You decide its height**: in the example, the container takes the full screen height minus a 64-pixel navigation bar.

**2. Switch the page to the embedded chat**

Set `window.homieBotConfig.embeddedChat` **before** the embed script loads. This tells the script that this page shows the embedded chat instead of the widget:

```html assistant.html theme={null}
<script>
  window.homieBotConfig = {
    embeddedChat: {},
  };
</script>
<script
  src="https://cdn.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  defer
></script>
```

> [!NOTE]
>
> Install the embedded chat with the homie embed script as shown here. Use the same assistant configuration as
> on your other shop pages.

**3. Open the page**

Reload the page. The chat appears in the container with its input at the bottom.

> [!NOTE]
>
> On a page with `embeddedChat`, the floating widget never appears. If the page has no element with the ID
> `homie-embedded-chat`, the script shows a warning in the browser console and displays nothing.

## Options

`embeddedChat` accepts these options:

```html theme={null}
<script>
    window.homieBotConfig = {
        embeddedChat: {
            title: 'How can we help you today?',
            contextUrl: 'https://www.example-store.com/products/rain-jacket-123',
        },
    };
</script>
```

**title** `string`

Optional plain-text heading above the conversation. Leading and trailing whitespace is removed. If omitted or blank, a greeting in the chat language is shown (e.g. “Hello”).

**contextUrl** `string`

Optional page to use as context, for example the product page the shopper came from. It determines the product
context, greeting, starter questions, and page settings. Relative URLs resolve against the current page. If omitted
or blank, the browser's referring page is used only if it is a different page with the same protocol, hostname, and
port. Otherwise, the assistant page provides the context.

## Example: from a product page to the assistant page

A button on your product page opens the assistant page and passes the product page along:

```html product-page.html theme={null}
<a href="/assistant?from=/products/rain-jacket-123">Ask our assistant</a>
```

On the assistant page, read the parameter and hand it to the embedded chat:

```html assistant.html theme={null}
<div id="homie-embedded-chat" style="height: calc(100dvh - 64px);"></div>

<script>
    const from = new URLSearchParams(window.location.search).get('from');
    window.homieBotConfig = {
        embeddedChat: {
            title: 'Questions about this product?',
            ...(from ? { contextUrl: from } : {}),
        },
    };
</script>
<script src="https://cdn.yourhomie.ai/embed.min.js" chatbotId="YOUR-CHATBOT-ID" defer></script>
```

Relative URLs like `/products/rain-jacket-123` are resolved against your shop's address.

> [!TIP]
>
> Ask "What is this product made of?" on the assistant page. The assistant answers about the product from the page you
> came from.

## Shops that change pages without reloading

If your shop changes pages without a full reload (a single-page app), the script loads once and keeps running. Do
not set `embeddedChat` in that case. Instead, show and remove the embedded chat yourself with two methods. Like all methods of the
Client API, they are available once the API is ready, so wait for the `homiebot:api-ready` event:

* [`window.homieBot.mountEmbeddedChat(options)`](https://docs.yourhomie.ai/en/api-reference/client/methods#mountembeddedchatoptions) hides the widget and shows the chat in `#homie-embedded-chat`. It
  accepts the same `title` and `contextUrl` options. Call it after the assistant page has rendered the container.
* [`window.homieBot.unmountEmbeddedChat()`](https://docs.yourhomie.ai/en/api-reference/client/methods#unmountembeddedchat) removes the chat and brings the widget back. Call it when the shopper
  leaves the assistant page.

See the [component lifecycle example](https://docs.yourhomie.ai/en/api-reference/client/methods.md#example-component-lifecycle-in-a-single-page-shop)
for mounting when the page opens and unmounting when it is left, including waiting for the Client API.

Pass the product page as `contextUrl` here: the browser's referring page does not update when you
change pages without reloading. As long as the embedded chat is shown, the widget stays hidden.

## Layout on mobile devices

* The chat column is centered and up to about 760 pixels wide; on narrow screens it uses the full width.
* Only the conversation scrolls. The header with the assistant's name and the reset button stays at the top, the input stays at the bottom.
* Use `dvh` units for the container height, as in the examples, so the input stays visible when the on-screen
  keyboard opens.
* Product links open in a new tab, so shoppers keep the conversation open.

## Troubleshooting

> **Nothing appears on the assistant page**
>
> Check that the container has exactly the ID `homie-embedded-chat` and exists when the script runs or when you
> call `mountEmbeddedChat`. The browser console shows a warning if the element is missing.

> **The widget appears instead of the embedded chat**
>
> Check that `window.homieBotConfig.embeddedChat` is set before the embed script loads, or, in a shop without
> reloads, that `mountEmbeddedChat` is called on the assistant page.

> **The chat is not visible or very small**
>
> The chat takes the height of its container. Give the container an explicit height, for example `calc(100dvh -
>             64px)`.

> **The assistant does not know the product**
>
> Pass the product page as `contextUrl`. Without it, the previous page is only used when the shopper came from a
> page of your own shop with a full page load.

## Next steps

> **[Configuration](https://docs.yourhomie.ai/en/api-reference/client/configuration.md)**
>
> All options of the embed script.

> **[Page configuration](https://docs.yourhomie.ai/en/user-guide/assistants/page-configuration.md)**
>
> Set greetings and starter questions per page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.