Fehlerbehebung

window.homieBot ist undefined

Das Objekt existiert erst, nachdem das Embed initialisiert wurde — beim Seitenaufruf kann es daher undefined sein.

Stelle sicher, dass das Skript tatsächlich lädt. Prüfe im Netzwerk-Tab, ob embed.min.js mit 200 zurückkommt.
Stelle sicher, dass chatbotId am Script-Tag oder in window.homieBotConfig gesetzt ist. Ohne sie loggt das Embed einen Fehler und stoppt.
Höre auf das Event homiebot:api-ready, statt direkt auf window.homieBot zuzugreifen.
Für ältere Embed-Versionen oder spät gebundenen Code nutze den waitForHomie()-Polling-Fallback aus den Beispielen.

Nachrichten werden nicht gesendet

sendMessage und getHistory benötigen ein bereites Chat-Iframe, nicht nur window.homieBot.

Warte auf das Event homiebot:assistant-ready oder prüfe window.homieBot.isReady(), bevor du sendest.
Das Iframe lädt verzögert beim ersten Öffnen. Rufst du sendMessage auf, öffnet es den Chat und wartet intern, aber das Promise wird abgelehnt, wenn das Iframe nie bereit wird (z. B. wenn es blockiert ist).
Prüfe, ob die Seite Iframes über eine strikte Content Security Policy (CSP) blockiert und ob Drittanbieter-Skripte nicht über document.readyState === "complete" hinaus verzögert werden.

Origin- oder Domain-Mismatch

Das Embed validiert jede postMessage gegen die konfigurierte domain und verwirft Nachrichten von jedem anderen Origin stillschweigend.

Stelle sicher, dass das domain-Attribut (oder homieBotConfig.domain) exakt mit dem Origin übereinstimmt, der den Chat ausliefert — in den meisten Fällen https://chat.yourhomie.ai.
Ein abschließender Slash oder ein http- vs. https-Mismatch reicht aus, um es zu brechen.
Öffnet der Chat, kommen aber nie Antworten an, prüfe, ob die API-Basis für deine Umgebung erreichbar ist (api.yourhomie.ai).

Metadaten bleiben in einer SPA über Seiten hinweg bestehen

Mit updateMessageMetadata() gesetzte Metadaten liegen im globalen Window-Kontext und werden bei clientseitiger Navigation nicht gelöscht.

Lösche veraltete Schlüssel bei jedem Routenwechsel, indem du updateMessageMetadata() mit null-Werten aufrufst.
Beachte die Limits pro Aufruf: max. 5 Schlüssel, Schlüssel ≤ 50 Zeichen, Wert ≤ 100 Zeichen.

window.homieBot.updateMessageMetadata({ productId: null, category: null, source: null });

Das Widget ist nicht sichtbar

Das Embed lädt, aber es erscheint kein Launcher-Button oder Chat.

Der Assistent ist auf der Plattform möglicherweise inaktiv oder auf privat gesetzt — in diesen Fällen beendet sich das Embed frühzeitig.
Eine Seiten-Konfiguration kann den Chatbot auf der aktuellen URL ausblenden.
Der Launcher kann hinter Sticky-Headern oder Badges liegen. Erhöhe shadowHostZIndex in deinen Plattform-Style-Einstellungen, um ihn über andere Elemente zu heben.
Der Launcher-Button kann absichtlich ausgeblendet sein (hideToggleButton); öffne den Chat dann selbst mit window.homieBot.open().

FAQ