Embedded Chat

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.

Before you start, make sure you have: - The homie embed script installed on your site (see Manual) - A page in your shop that should show the assistant, for example /assistant

Add the embedded chat to a page

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.

assistant.html

<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.

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:

assistant.html

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

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

Open the page

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

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:

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

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”).

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:

product-page.html

<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:

assistant.html

<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.

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) 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() removes the chat and brings the widget back. Call it when the shopper leaves the assistant page.

See the component lifecycle example 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

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.

Get Started

Assistants

Knowledge

Chat tags

Product Questions

Tools

Integrations

Settings

Account

Add the embedded chat to a page

Options

Example: from a product page to the assistant page

Shops that change pages without reloading

Layout on mobile devices

Troubleshooting

Next steps

Configuration

Page configuration

​Add the embedded chat to a page

​Options

​Example: from a product page to the assistant page

​Shops that change pages without reloading

​Layout on mobile devices

​Troubleshooting

​Next steps

Configuration

Page configuration

Add the embedded chat to a page

Options

Example: from a product page to the assistant page

Shops that change pages without reloading

Layout on mobile devices

Troubleshooting

Next steps