Embedded Chat

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.

Bevor du startest, stelle sicher, dass du Folgendes hast: - Das homie Embed Script auf deiner Website (siehe Manuell) - Eine Seite in deinem Shop, die den Assistenten zeigen soll, zum Beispiel /assistent

Embedded Chat auf einer Seite einbauen

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.

assistent.html

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

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:

assistent.html

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

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

Seite öffnen

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

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:

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

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

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:

produktseite.html

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

assistent.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: '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.

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) 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() entfernt den Chat und bringt das Widget zurück. Rufe sie auf, wenn deine Kund:innen die Assistenten-Seite verlassen.

Das Komponenten-Lifecycle-Beispiel 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

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.

Erste Schritte

Assistenten

Wissen

Chat-Tags

Produktfragen

Tools

Integrationen

Einstellungen

Konto

Embedded Chat auf einer Seite einbauen

Optionen

Beispiel: von der Produktseite zur Assistenten-Seite

Shops, die Seiten ohne Neuladen wechseln

Darstellung auf Mobilgeräten

Fehlerbehebung

Nächste Schritte

Konfiguration

Seitenkonfiguration

​Embedded Chat auf einer Seite einbauen

​Optionen

​Beispiel: von der Produktseite zur Assistenten-Seite

​Shops, die Seiten ohne Neuladen wechseln

​Darstellung auf Mobilgeräten

​Fehlerbehebung

​Nächste Schritte

Konfiguration

Seitenkonfiguration

Embedded Chat auf einer Seite einbauen

Optionen

Beispiel: von der Produktseite zur Assistenten-Seite

Shops, die Seiten ohne Neuladen wechseln

Darstellung auf Mobilgeräten

Fehlerbehebung

Nächste Schritte