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

# Methods

> Complete API reference for all available window.homieBot methods.

## API Reference: `window.homieBot`

### `open()`

Opens the chat (if closed).

```js theme={null}
window.homieBot.open();
```

### `close()`

Closes the chat (if open).

```js theme={null}
window.homieBot.close();
```

### `toggle()`

Toggles between open/closed.

```js theme={null}
window.homieBot.toggle();
```

### `isOpen()` → `boolean`

Returns whether the chat is currently open.

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

```js theme={null}
await window.homieBot.sendMessage(
  { text: 'Do you have this product in grey?' },
  { open: true } // opens the chat before sending
);
```

**`input` (required: `text`)**

| Field        | Type    | Description                                |
| ------------ | ------- | ------------------------------------------ |
| `text`       | string  | The message to inject.                     |
| `id`         | string  | (optional) Your own reference/tracking ID. |
| `setId`      | string  | (optional) Question set ID for tracking.   |
| `questionId` | string  | (optional) Question ID within the set.     |
| `newChat`    | boolean | (optional) Start a new conversation.       |

**`options`**

| Field           | Type    | Default | Description                                 |
| --------------- | ------- | ------- | ------------------------------------------- |
| `open`          | boolean | `true`  | Open chat if closed.                        |
| `maxRetries`    | number  | `3`     | Retries while the iFrame initializes.       |
| `retryDelay`    | number  | `300`   | Milliseconds between retries.               |
| `timeout`       | number  | `5000`  | Total timeout in ms waiting for ACK.        |
| `relaxedOrigin` | boolean | `false` | Disable origin checks (special cases only). |

### `getHistory()` → `Promise<any>`

Returns the current chat history (useful for Custom-Tracking).

```js theme={null}
const history = await window.homieBot.getHistory();
console.log('Chat history:', history);
```

### `updateMessageMetadata(metadata)` → `void`

Adds metadata to the next user message as key-value pairs. The metadata is sent to the chat widget. If the widget is not yet initialized, the metadata is stored in a pending state and automatically sent once the widget is ready.

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

**Limits & Validation**

| Constraint   | Limit                              |
| ------------ | ---------------------------------- |
| Max Keys     | 5 key-value pairs per call         |
| Key Length   | Max 50 characters                  |
| Value Length | Max 100 characters                 |
| Key Type     | Must be string                     |
| Value Type   | String or `null` (to remove a key) |

**Overwriting Metadata**

* Existing keys can be overwritten with new values
* Keys can be removed by passing `null` as the value
* Multiple calls to `updateMessageMetadata()` are merged — new keys are added, existing keys are updated

```js theme={null}
// Set initial metadata
window.homieBot.updateMessageMetadata({
  productId: '12345',
  category: 'power-tools',
});

// Update existing key and add new one
window.homieBot.updateMessageMetadata({
  category: 'hand-tools', // overwrites existing
  brand: 'Bosch', // adds new key
});

// Remove a key
window.homieBot.updateMessageMetadata({
  brand: null, // removes the key
});
```

<Warning>
  **Single-Page Applications (SPAs):** Metadata keys persist across navigation since they are stored in the global
  window context. When navigating between pages, you must manually clear the metadata by calling{' '}
  <code>updateMessageMetadata()</code> with <code>null</code> values to avoid unintended persistence.
</Warning>

```js theme={null}
// Clear metadata on route change in SPA
window.homieBot.updateMessageMetadata({
  productId: null,
  category: null,
  source: null,
});
```