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

# Examples

> Practical recipes for opening the widget, sending messages, attaching metadata, and reading history.

These recipes cover the most common Client API integrations. They all assume the embed script is installed — see the [overview](/en/api-reference/client/overview) and [configuration](/en/api-reference/client/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:

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
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:

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

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

```js theme={null}
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:

```js theme={null}
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`:

```js theme={null}
window.homieBot.sendMessage({ text: 'Start over, please.', newChat: true });
```