Skip to main content
This page documents the client-side Browser API exposed by the embed script. For server-side REST endpoints, see your API Reference.

​
Overview

Once the Homie embed script is loaded, a global object window.homieBot becomes available. Use it to open/close the widget, check its state, send messages programmatically, and read the chat history.

​
Requirements

  1. The script must be embedded on your page.
  2. chatbotId and domain must be set.
<script
  src="https://chat.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  domain="https://chat.yourhomie.ai"
  defer
></script>
The object window.homieBot is only available after the script has loaded. If you need to interact early, use the waitForHomie() helper below.

​
API Reference: window.homieBot

​
open()

Opens the chat (if closed). 
window.homieBot.open();

​
close()

Closes the chat (if open). 
window.homieBot.close();

​
toggle()

Toggles between open/closed. 
window.homieBot.toggle();

​
isOpen() → boolean

Returns whether the chat is currently open. 
if (window.homieBot.isOpen()) {
  console.log("Chat is open");
}

​
sendMessage(input, options?) → Promise<boolean>

Injects a message directly into the chat — ideal for PDPs or context-driven prompts. 
await window.homieBot.sendMessage(
  { text: "Do you have this product in grey?" },
  { open: true } // opens the chat before sending
);
input (required: text)
FieldTypeDescription
textstringThe message to inject.
idstring(optional) Your own reference/tracking ID.
setIdstring(optional) Question set ID for tracking.
questionIdstring(optional) Question ID within the set.
newChatboolean(optional) Start a new conversation.
options
FieldTypeDefaultDescription
openbooleantrueOpen chat if closed.
maxRetriesnumber3Retries while the iFrame initializes.
retryDelaynumber300Milliseconds between retries.
timeoutnumber5000Total timeout in ms waiting for ACK.
relaxedOriginbooleanfalseDisable origin checks (special cases only).

​
getHistory() → Promise<any>

Returns the current chat history (useful for Custom-Tracking). 
const history = await window.homieBot.getHistory();
console.log("Chat history:", history);

​
Practical Examples

​
1) Auto-open after 10 seconds

setTimeout(() => window.homieBot.open(), 10_000);

​
2) Trigger an intent on a PDP

window.homieBot.sendMessage({
  text: "Show me similar drills.",
  setId: "pdp-questions-set-123",
});

​
3) Open after scroll depth

function openAfterScroll(px = 600) {
  const onScroll = () => {
    if (window.scrollY > px) {
      window.homieBot.open();
      window.removeEventListener("scroll", onScroll);
    }
  };
  window.addEventListener("scroll", onScroll, { passive: true });
}
openAfterScroll();

​
Robust loading: waitForHomie()

If your code runs before the embed has finished loading, wait until window.homieBot exists: 
function waitForHomie() {
  return new Promise((resolve) => {
    if (window.homieBot) return resolve(window.homieBot);
    const iv = setInterval(() => {
      if (window.homieBot) {
        clearInterval(iv);
        resolve(window.homieBot);
      }
    }, 200);
  });
}

// Example usage
await waitForHomie();
window.homieBot.open();

​
Embedding & Configuration

At minimum, set chatbotId and domain on the script tag. Styling and behavior are managed from the Homie dashboard and pulled in automatically by the embed. 
<script
  src="https://chat.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  domain="https://chat.yourhomie.ai"
  defer
></script>
Optionally managed via your Homie style settings (fetched by the script):
  • iconColor, iconRounded, iconImage, iconSize, iconImagePadding
  • iconBottomPadding, iconSidePadding, iconAlign (left | right)
  • showHoverText, isPrivate, active
Advanced: Some customers provide window.homieUserConfig to pass user_id, user_hash, and user_metadata. The embed forwards these safely to the iFrame (Base64‑encoded metadata).

​
Troubleshooting

  • window.homieBot is undefined → Ensure the script actually loads (Network tab) and use waitForHomie().
  • No response to sendMessage → Check if the site blocks iFrames, uses strict CSP, or delays third‑party scripts. Also, wait for document.readyState === "complete".
  • Chat opens but no replies → Verify API base access depending on the domain (api.yourhomie.ai, staging.api.yourhomie.ai, dev.api.yourhomie.ai).
  • Checkout specific → The embed preloads the iFrame automatically when a configured checkoutUrl matches. Verify exact URLs during testing.

​
FAQ

Can I force a new conversation?
Yes: sendMessage({ text: "...", newChat: true }). How are question events tracked?
If setId (and optionally questionId) are provided, the script sends a fire‑and‑forget tracking call to the public endpoint in the background. This does not affect the message injection itself. Can I query the state without opening the chat?
Yes, isOpen() returns the state and does not alter the UI.

​
TL;DR

MethodPurpose
open()Open the chat
close()Close the chat
toggle()Toggle open/closed
isOpen()Read current state
sendMessage(input, options?)Inject a message (with retry/timeout)
getHistory()Read the current history