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

# Introduction

> Control the embedded homie chat widget from your website using the global browser API window.homieBot.

The Client API is a browser-side JavaScript interface exposed by the homie embed script. Once the script loads, a global `window.homieBot` object becomes available so you can open or close the widget, check its state, send messages programmatically, attach metadata, and read the chat history — all from your own page code.

<Note>
  This page documents the client-side browser API exposed by the embed script. For server-side REST endpoints, see the
  [REST API](/en/api-reference/backend/overview).
</Note>

## Install the embed script

Add the embed script to your page. Styling and behavior are managed from the homie platform and pulled in automatically by the embed.

```html theme={null}
<script
  src="https://cdn.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  defer
></script>
```

For platform-specific install steps, see the [Installation overview](/en/user-guide/installation/overview).

## Requirements

1. The script must be embedded on your page.
2. `chatbotId` must be set (on the script tag or via `window.homieBotConfig`).

See [Configuration](/en/api-reference/client/configuration) for all script attributes and global config objects.

## When the API is available

The `window.homieBot` object only exists **after** the embed has initialized. Do not assume it is present at page load.

<Warning>
  Reading `window.homieBot` immediately on page load may return `undefined`. Listen for the `homiebot:api-ready` event,
  or use the `waitForHomie()` polling fallback shown in the [examples](/en/api-reference/client/examples).
</Warning>

The embed dispatches browser events as it reaches each lifecycle stage:

| Event                      | When                                                  |
| -------------------------- | ----------------------------------------------------- |
| `homiebot:api-ready`       | `window.homieBot` is available                        |
| `homiebot:assistant-ready` | Chat iframe is ready for `sendMessage` / `getHistory` |
| `homiebot:opened`          | Chat widget was opened                                |
| `homiebot:closed`          | Chat widget was closed                                |

Each event carries `{ chatbotId }` in `event.detail`. See [Events](/en/api-reference/client/events) for full details.

## Methods at a glance

| Method                                          | Purpose                                           |
| ----------------------------------------------- | ------------------------------------------------- |
| `open()`                                        | Open the chat                                     |
| `close()`                                       | Close the chat                                    |
| `toggle()`                                      | Toggle open/closed                                |
| `isOpen()`                                      | Read whether the widget is open                   |
| `isReady()`                                     | Read whether the iframe is ready for messages     |
| `sendMessage(input, options?)`                  | Inject a message into the chat                    |
| `getHistory()`                                  | Read the current chat history                     |
| `updateMessageMetadata(metadata)`               | Attach metadata to the next user message          |
| `sendCustomPdpQuestion(questionSetId)`          | Open the custom product-question flow             |
| `trackPdpQuestionsView(element, questionSetId)` | Report a view for self-rendered product questions |

See [Methods](/en/api-reference/client/methods) for the full reference.

## Explore the Client API

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/en/api-reference/client/configuration">
    Script attributes, global config objects, language and Shopify market resolution.
  </Card>

  <Card title="Methods" icon="code" href="/en/api-reference/client/methods">
    Full reference for every method on `window.homieBot`.
  </Card>

  <Card title="Events" icon="bell" href="/en/api-reference/client/events">
    Browser events dispatched by the embed for lifecycle and interaction.
  </Card>

  <Card title="Examples" icon="lightbulb" href="/en/api-reference/client/examples">
    Practical recipes for opening, messaging, and tracking.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/en/api-reference/client/troubleshooting">
    Fixes for the most common integration issues.
  </Card>
</CardGroup>