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

> Zeige den homie-Assistenten als eigene Seite in deinem Shop: Deine Navigation bleibt oben, der Chat füllt den Seiteninhalt darunter.

Mit dem Embedded Chat wird der Assistent zu einer Seite deines Shops statt zu einem schwebenden Widget. Dein Shop behält seine eigene Navigationsleiste und seinen Zurück- oder Schließen-Button, der Chat sitzt als mittige Spalte im Seiteninhalt darunter. Deine Kund:innen sehen dabei dasselbe Gespräch wie im Widget auf deinen anderen Seiten.

> [!NOTE]
>
> Bevor du startest, stelle sicher, dass du Folgendes hast: - Das homie Embed Script auf deiner Website (siehe
> [Manuell](https://docs.yourhomie.ai/de/user-guide/installation/manual.md)) - Eine Seite in deinem Shop, die den Assistenten zeigen soll, zum
> Beispiel `/assistent`

## Embedded Chat auf einer Seite einbauen

**1. Container hinzufügen**

Füge dort, wo der Chat erscheinen soll, unter deiner Navigationsleiste ein leeres Element mit der ID `homie-embedded-chat` ein. Die ID ist fest vorgegeben und lässt sich nicht ändern. Lass das Element leer: Inhalte darin werden nicht angezeigt.

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

Der Chat füllt den Container vollständig aus. **Die Höhe bestimmst du**: Im Beispiel nimmt der Container die volle Bildschirmhöhe abzüglich einer 64 Pixel hohen Navigationsleiste ein.

**2. Seite auf den Embedded Chat umstellen**

Setze `window.homieBotConfig.embeddedChat`, **bevor** das Embed Script lädt. Damit weiß das Script, dass diese Seite den Embedded Chat statt des Widgets zeigt:

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

> [!NOTE]
>
> Binde den Embedded Chat wie hier gezeigt mit dem homie Embed Script ein. Verwende dieselbe
> Assistenten-Konfiguration wie auf deinen anderen Shopseiten.

**3. Seite öffnen**

Lade die Seite neu. Der Chat erscheint im Container, das Eingabefeld unten.

> [!NOTE]
>
> Auf einer Seite mit `embeddedChat` erscheint nie das schwebende Widget. Fehlt das Element mit der ID
> `homie-embedded-chat`, zeigt das Script eine Warnung in der Browser-Konsole und sonst nichts an.

## Optionen

`embeddedChat` kennt diese Optionen:

```html theme={null}
<script>
    window.homieBotConfig = {
        embeddedChat: {
            title: 'Wie können wir dir heute helfen?',
            contextUrl: 'https://www.example-store.com/products/regenjacke-123',
        },
    };
</script>
```

**title** `string`

Optionale Überschrift als reiner Text über dem Gespräch. Leerzeichen am Anfang und Ende werden entfernt. Ohne Angabe oder bei leerem Wert erscheint eine Begrüßung in der Chatsprache (z. B. „Hallo“).

**contextUrl** `string`

Optionale Seite als Kontext, etwa die Produktseite, von der deine Kund:innen kommen. Sie bestimmt den
Produktkontext, die Begrüßung, Startfragen und Seiteneinstellungen. Relative URLs beziehen sich auf die aktuelle
Seite. Ohne Angabe oder bei einer leeren Zeichenfolge wird die vom Browser übermittelte Herkunftsseite nur genutzt,
wenn sie eine andere Seite mit gleichem Protokoll, Hostnamen und Port ist. Andernfalls dient die Assistenten-Seite
als Kontext.

## Beispiel: von der Produktseite zur Assistenten-Seite

Ein Button auf deiner Produktseite öffnet die Assistenten-Seite und gibt die Produktseite mit:

```html produktseite.html theme={null}
<a href="/assistent?from=/products/regenjacke-123">Frag unseren Assistenten</a>
```

Auf der Assistenten-Seite liest du den Parameter aus und gibst ihn an den Embedded Chat weiter:

```html assistent.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: 'Fragen zu diesem Produkt?',
            ...(from ? { contextUrl: from } : {}),
        },
    };
</script>
<script src="https://cdn.yourhomie.ai/embed.min.js" chatbotId="YOUR-CHATBOT-ID" defer></script>
```

Relative URLs wie `/products/regenjacke-123` werden gegen die Adresse deines Shops aufgelöst.

> [!TIP]
>
> Frage auf der Assistenten-Seite „Aus welchem Material ist dieses Produkt?“. Der Assistent antwortet zum Produkt der
> Seite, von der du gekommen bist.

## Shops, die Seiten ohne Neuladen wechseln

Wechselt dein Shop Seiten ohne vollständiges Neuladen (Single-Page-App), lädt das Script nur einmal und läuft weiter.
Setze `embeddedChat` in diesem Fall nicht. Zeige und entferne den Embedded Chat stattdessen selbst mit zwei
Methoden. Wie alle Methoden der Client API stehen sie bereit, sobald die API bereit ist. Warte also auf das Event
`homiebot:api-ready`:

* [`window.homieBot.mountEmbeddedChat(options)`](https://docs.yourhomie.ai/de/api-reference/client/methods#mountembeddedchatoptions) blendet das Widget aus und zeigt den Chat in `#homie-embedded-chat`.
  Die Methode kennt dieselben Optionen `title` und `contextUrl`. Rufe sie auf, nachdem die Assistenten-Seite den
  Container gerendert hat.
* [`window.homieBot.unmountEmbeddedChat()`](https://docs.yourhomie.ai/de/api-reference/client/methods#unmountembeddedchat) entfernt den Chat und bringt das Widget zurück. Rufe sie auf, wenn deine
  Kund:innen die Assistenten-Seite verlassen.

Das [Komponenten-Lifecycle-Beispiel](https://docs.yourhomie.ai/de/api-reference/client/methods.md#beispiel-komponenten-lifecycle-in-einem-single-page-shop)
zeigt den Einbau beim Öffnen und den Abbau beim Verlassen der Seite einschließlich des Wartens auf die Client API.

Übergib hier die Produktseite als `contextUrl`: Die vom Browser übermittelte Herkunftsseite ändert sich bei
einem Seitenwechsel ohne Neuladen nicht. Solange der Embedded Chat angezeigt wird, bleibt das Widget ausgeblendet.

## Darstellung auf Mobilgeräten

* Die Chat-Spalte ist mittig und bis zu etwa 760 Pixel breit; auf schmalen Bildschirmen nutzt sie die volle Breite.
* Nur das Gespräch scrollt. Der Kopf mit dem Namen des Assistenten und dem Zurücksetzen-Button bleibt oben, das Eingabefeld bleibt unten.
* Nutze wie in den Beispielen `dvh`-Einheiten für die Höhe des Containers, damit das Eingabefeld sichtbar bleibt, wenn
  sich die Bildschirmtastatur öffnet.
* Produktlinks öffnen sich in einem neuen Tab, damit deine Kund:innen das Gespräch offen behalten.

## Fehlerbehebung

> **Auf der Assistenten-Seite erscheint nichts**
>
> Prüfe, dass der Container genau die ID `homie-embedded-chat` hat und existiert, wenn das Script läuft oder wenn
> du `mountEmbeddedChat` aufrufst. Fehlt das Element, zeigt die Browser-Konsole eine Warnung.

> **Statt des Embedded Chats erscheint das Widget**
>
> Prüfe, dass `window.homieBotConfig.embeddedChat` gesetzt ist, bevor das Embed Script lädt, oder dass in einem
> Shop ohne Neuladen `mountEmbeddedChat` auf der Assistenten-Seite aufgerufen wird.

> **Der Chat ist nicht sichtbar oder sehr klein**
>
> Der Chat übernimmt die Höhe seines Containers. Gib dem Container eine feste Höhe, zum Beispiel `calc(100dvh -
>             64px)`.

> **Der Assistent kennt das Produkt nicht**
>
> Übergib die Produktseite als `contextUrl`. Ohne sie wird die vorherige Seite nur genutzt, wenn deine Kund:innen
> mit einem vollständigen Seitenaufruf von einer Seite deines eigenen Shops kommen.

## Nächste Schritte

> **[Konfiguration](https://docs.yourhomie.ai/de/api-reference/client/configuration.md)**
>
> Alle Optionen des Embed Scripts.

> **[Seitenkonfiguration](https://docs.yourhomie.ai/de/user-guide/assistants/page-configuration.md)**
>
> Begrüßung und Startfragen pro Seite festlegen.


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