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

# Events

> Browser events dispatched by the homie embed.

The embed dispatches `CustomEvent`s on `window` so you can react to lifecycle and interaction without polling. For almost all integrations, these events plus the [methods](/en/api-reference/client/methods) are all you need.

Every event includes these fields in `event.detail`:

| Field        | Type                  | Description                                         |
| ------------ | --------------------- | --------------------------------------------------- |
| `chatbotId`  | `string`              | Assistant identifier                                |
| `storeId`    | `string \| undefined` | Store identifier when one is configured or resolved |
| `chatId`     | `string \| undefined` | Conversation identifier once a conversation exists  |
| `occurredAt` | `string`              | Event time as an ISO 8601 timestamp                 |

## Browser events

| Event                         | When it fires                                             | `event.detail`                                 |
| ----------------------------- | --------------------------------------------------------- | ---------------------------------------------- |
| `homiebot:api-ready`          | `window.homieBot` is available                            | Common fields                                  |
| `homiebot:assistant-ready`    | The chat iframe is ready for `sendMessage` / `getHistory` | Common fields                                  |
| `homiebot:opened`             | The chat widget was opened                                | Common fields                                  |
| `homiebot:closed`             | The chat widget was closed                                | Common fields                                  |
| `homiebot:chat-started`       | A new conversation was created for the first user message | Common fields; `chatId` is required            |
| `homiebot:message-sent`       | A valid user message was added and delivery began         | Common fields plus `inputType`                 |
| `homiebot:message-received`   | A complete assistant response was received                | Common fields plus `messageId`, `productCount` |
| `homiebot:chat-reset`         | An existing conversation was cleared                      | Common fields plus `reason`                    |
| `homiebot:product-clicked`    | A recommended product was selected                        | Common fields plus `product`                   |
| `homiebot:feedback-submitted` | Like or dislike feedback was submitted                    | Common fields plus `messageId`, `rating`       |

<Note>
  `homiebot:opened` and `homiebot:closed` fire for every open/close action — the launcher button, welcome bubbles,
  `window.homieBot.open()` / `.close()` / `.toggle()`, and actions triggered from inside the chat.
</Note>

<Note>
  Message and response content, user identifiers, feedback text, and internal errors are never included in browser event
  payloads.
</Note>

### Listen for the API

Fired once `window.homieBot` is usable.

```js theme={null}
window.addEventListener('homiebot:api-ready', (e) => {
  const { chatbotId } = e.detail;
  console.log('homie API ready', chatbotId);
  window.homieBot.open();
});
```

### Listen for the assistant

Fired once the iframe is ready for `sendMessage` and `getHistory`.

```js theme={null}
window.addEventListener('homiebot:assistant-ready', () => {
  window.homieBot.sendMessage({ text: 'Hello', newChat: false });
});
```

### Track a conversation funnel

Useful for forwarding interactions to analytics.

```js theme={null}
window.addEventListener('homiebot:opened', (e) => {
  window.dataLayer?.push({ event: 'homie_chat_opened', chatbotId: e.detail.chatbotId });
});

window.addEventListener('homiebot:chat-started', (e) => {
  window.dataLayer?.push({
    event: 'homie_chat_started',
    chatbotId: e.detail.chatbotId,
    chatId: e.detail.chatId,
    storeId: e.detail.storeId,
  });
});

window.addEventListener('homiebot:message-received', (e) => {
  window.dataLayer?.push({
    event: 'homie_message_received',
    chatId: e.detail.chatId,
    productCount: e.detail.productCount,
  });
});
```

## Interaction payloads

### Message sent

`inputType` is one of `text`, `speech`, `suggestion`, `pdp-question`, or `api`.

```js theme={null}
{
  chatbotId: 'assistant-id',
  storeId: 'store-id',
  chatId: 'chat-id',
  occurredAt: '2026-07-30T12:34:56.000Z',
  inputType: 'suggestion'
}
```

### Message received

This event fires once for the complete response, including streamed responses. `productCount` is `0` when the response
does not contain product recommendations.

```js theme={null}
{
  chatbotId: 'assistant-id',
  storeId: 'store-id',
  chatId: 'chat-id',
  occurredAt: '2026-07-30T12:34:57.000Z',
  messageId: 'message-id',
  productCount: 3
}
```

### Chat reset

`reason` is one of `manual`, `inactivity`, or `api`. The `chatId` identifies the conversation that was cleared.

### Product clicked

The `product` object contains only `gtin`, `brand`, `designation`, and `url`.

### Feedback submitted

`rating` is either `like` or `dislike`. Feedback reasons and free text are not exposed.