Skip to main content
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.
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.
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".
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).
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.
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().

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