Examples - homie Documentation

These recipes cover the most common Client API integrations. They all assume the embed script is installed — see the overview and configuration.

Wait until the API is ready

The embed dispatches browser events when it is ready. Prefer listening for these instead of polling. If your code might run before or after the embed is ready, check once and then listen:

if (window.homieBot) {
  if (window.homieBot.isReady()) {
    window.homieBot.open();
  } else {
    window.addEventListener('homiebot:assistant-ready', () => window.homieBot.open(), { once: true });
  }
} else {
  window.addEventListener('homiebot:api-ready', () => window.homieBot.open(), { once: true });
}

Polling fallback for older embed versions without events:

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);
  });
}

await waitForHomie();
window.homieBot.open();

Auto-open on intent

Open the widget after a delay to invite engagement:

window.addEventListener('homiebot:api-ready', () => {
  setTimeout(() => window.homieBot.open(), 10_000);
});

Open after scroll depth

Open the chat once the visitor scrolls past a threshold:

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

window.addEventListener('homiebot:api-ready', () => openAfterScroll());

Trigger a product question

Inject a context-driven prompt from a product detail page. sendMessage opens the chat automatically if it is closed:

window.addEventListener('homiebot:assistant-ready', () => {
  document.querySelector('#ask-about-product')?.addEventListener('click', () => {
    window.homieBot.sendMessage({
      text: 'Do you have this product in grey?',
      newChat: false,
    });
  });
});

To trigger the custom product-question flow for a question set:

window.homieBot.sendCustomPdpQuestion('pdp-questions-set-123');

Attach metadata to the next message

Add context such as the current product before the visitor sends a message:

window.homieBot.updateMessageMetadata({
  productId: '12345',
  category: 'power-tools',
  source: 'pdp',
});

In a single-page app, clear stale metadata on navigation:

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

Read the chat history

Read the current conversation, for example to forward it to your own analytics:

window.addEventListener('homiebot:assistant-ready', async () => {
  const history = await window.homieBot.getHistory();
  console.log('Chat history:', history);
});

Force a new conversation

Start a fresh conversation by setting newChat: true:

window.homieBot.sendMessage({ text: 'Start over, please.', newChat: true });

​Wait until the API is ready

​Auto-open on intent

​Open after scroll depth

​Trigger a product question

​Attach metadata to the next message

​Read the chat history

​Force a new conversation