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

# Fehlerbehebung

> Lösungen für die häufigsten Probleme bei der Integration der homie Client-API.

Die meisten Client-API-Probleme liegen am Timing (Methoden werden aufgerufen, bevor das Embed bereit ist) oder an Origin-Mismatches. Arbeite die Abschnitte unten von oben nach unten durch.

<AccordionGroup>
  <Accordion title="window.homieBot ist undefined" icon="ghost">
    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](/de/api-reference/client/examples).
  </Accordion>

  <Accordion title="Nachrichten werden nicht gesendet" icon="paper-plane">
    `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.
  </Accordion>

  <Accordion title="Origin- oder Domain-Mismatch" icon="shield">
    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`).
  </Accordion>

  <Accordion title="Metadaten bleiben in einer SPA über Seiten hinweg bestehen" icon="arrows-rotate">
    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.

    ```js theme={null}
    window.homieBot.updateMessageMetadata({ productId: null, category: null, source: null });
    ```
  </Accordion>

  <Accordion title="Das Widget ist nicht sichtbar" icon="eye-slash">
    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()`.
  </Accordion>
</AccordionGroup>

## FAQ

**Kann ich eine neue Konversation erzwingen?**
Ja — `sendMessage({ text: '...', newChat: true })`.

**Kann ich den Widget-Zustand lesen, ohne es zu öffnen?**
Ja — `isOpen()` gibt den aktuellen Zustand zurück und verändert die UI nicht.

**Woher weiß ich, dass das Iframe für Nachrichten bereit ist?**
Prüfe `isReady()` oder höre auf das Event `homiebot:assistant-ready`.