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

# Troubleshooting

> Fixes for the most common issues integrating the homie Client API.

Most Client API issues come down to timing (calling methods before the embed is ready) or origin mismatches. Work through the sections below from top to bottom.

<AccordionGroup>
  <Accordion title="window.homieBot is undefined" icon="ghost">
    The object only exists after the embed initializes, so reading it on page load can return `undefined`.

    * Confirm the script actually loads. Check the browser Network tab for `embed.min.js` returning `200`.
    * Confirm `chatbotId` is set on the script tag or in `window.homieBotConfig`. Without it, the embed logs an error and stops.
    * Listen for the `homiebot:api-ready` event instead of accessing `window.homieBot` directly.
    * For older embed versions or late-bound code, use the `waitForHomie()` polling fallback from the [examples](/en/api-reference/client/examples).
  </Accordion>

  <Accordion title="Messages are not sending" icon="paper-plane">
    `sendMessage` and `getHistory` need the chat iframe to be ready, not just `window.homieBot`.

    * Wait for the `homiebot:assistant-ready` event, or check `window.homieBot.isReady()` before sending.
    * The iframe loads lazily on first open. If you call `sendMessage` it opens the chat and waits internally, but the promise rejects if the iframe never becomes ready (for example if it is blocked).
    * Check that the site does not block iframes via a strict Content Security Policy (CSP), and that third-party scripts are not delayed past `document.readyState === "complete"`.
  </Accordion>

  <Accordion title="Origin or domain mismatch" icon="shield">
    The embed validates every `postMessage` against the configured `domain`, and silently drops messages from any other origin.

    * Make sure the `domain` attribute (or `homieBotConfig.domain`) exactly matches the origin serving the chat — `https://chat.yourhomie.ai` in most cases.
    * A trailing slash or `http` vs `https` mismatch is enough to break it.
    * If the chat opens but replies never arrive, verify the API base for your environment is reachable (`api.yourhomie.ai`).
  </Accordion>

  <Accordion title="Metadata persists across pages in an SPA" icon="arrows-rotate">
    Metadata set with `updateMessageMetadata()` lives in the global window context and is **not** cleared on client-side navigation.

    * Clear stale keys on every route change by calling `updateMessageMetadata()` with `null` values.
    * Remember the per-call limits: max 5 keys, key ≤ 50 characters, value ≤ 100 characters.

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

  <Accordion title="The widget is not visible" icon="eye-slash">
    The embed loads but no launcher button or chat appears.

    * The assistant may be inactive or set to private on the platform — the embed exits early in those cases.
    * A page configuration may hide the chatbot on the current URL.
    * The launcher can sit behind sticky headers or badges. Increase `shadowHostZIndex` in your platform style settings to lift it above other elements.
    * The launcher button may be intentionally hidden (`hideToggleButton`); in that case open the chat yourself with `window.homieBot.open()`.
  </Accordion>
</AccordionGroup>

## FAQ

**Can I force a new conversation?**
Yes — `sendMessage({ text: '...', newChat: true })`.

**Can I read the widget state without opening it?**
Yes — `isOpen()` returns the current state and does not change the UI.

**How do I know the iframe is ready for messages?**
Check `isReady()` or listen for the `homiebot:assistant-ready` event.