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

# Methoden

> Vollständige Referenz für jede Methode auf window.homieBot, mit Parametern, Rückgabetypen und Beispielen.

Alle Methoden liegen auf `window.homieBot`, das nach dem Event `homiebot:api-ready` verfügbar ist. Methoden, die Nachrichten senden oder lesen (`sendMessage`, `getHistory`, `sendCustomPdpQuestion`), benötigen ein bereites Iframe — sie warten intern, aber du kannst die Bereitschaft mit `isReady()` prüfen oder auf `homiebot:assistant-ready` hören.

<Note>
  Sichere dich immer dagegen ab, dass `window.homieBot` beim Seitenaufruf noch `undefined` ist. Siehe die
  [Beispiele](/de/api-reference/client/examples) für ein Wait-for-Ready-Muster.
</Note>

## open()

Öffnet das Chat-Widget, falls es aktuell geschlossen ist. Gibt `void` zurück.

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

## close()

Schließt das Chat-Widget, falls es aktuell offen ist. Gibt `void` zurück.

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

## toggle()

Wechselt das Widget zwischen offen und geschlossen. Gibt `void` zurück.

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

## isOpen()

Gibt `boolean` zurück — ob das Widget aktuell offen ist. Verändert die UI nicht.

```js theme={null}
if (window.homieBot.isOpen()) {
  console.log('Chat is open');
}
```

## isReady()

Gibt `boolean` zurück — ob das Chat-Iframe vollständig geladen und bereit für `sendMessage` und `getHistory` ist. Nutze dies, bevor du aus spät gebundenem Code Nachrichten sendest.

```js theme={null}
if (window.homieBot.isReady()) {
  window.homieBot.sendMessage({ text: 'Hello' });
}
```

## sendMessage(input, options?)

Fügt eine Nachricht direkt in den Chat ein — ideal für Produktdetailseiten (PDPs) oder kontextgetriebene Prompts. Öffnet den Chat zuerst, falls er geschlossen ist. Gibt ein `Promise` zurück.

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

**`input` (erforderlich: `text`)**

| Feld         | Typ     | Beschreibung                                   |
| ------------ | ------- | ---------------------------------------------- |
| `text`       | string  | Die einzufügende Nachricht.                    |
| `id`         | string  | (optional) Deine eigene Referenz-/Tracking-ID. |
| `setId`      | string  | (optional) Fragenset-ID fürs Tracking.         |
| `questionId` | string  | (optional) Frage-ID innerhalb des Sets.        |
| `newChat`    | boolean | (optional) Eine neue Konversation starten.     |

**`options`**

| Feld            | Typ     | Standard | Beschreibung                                      |
| --------------- | ------- | -------- | ------------------------------------------------- |
| `open`          | boolean | `true`   | Chat öffnen, falls geschlossen.                   |
| `maxRetries`    | number  | `3`      | Wiederholungen, während das Iframe initialisiert. |
| `retryDelay`    | number  | `300`    | Millisekunden zwischen Wiederholungen.            |
| `timeout`       | number  | `5000`   | Gesamt-Timeout in ms beim Warten auf das ACK.     |
| `relaxedOrigin` | boolean | `false`  | Origin-Prüfungen deaktivieren (nur Sonderfälle).  |

<Note>
  Die oben dokumentierte Signatur ist der unterstützte öffentliche Vertrag. Die aktuelle Embed-Quelle stellt eine
  vereinfachte Form `sendMessage(input)` bereit, bei der `input` die Felder `text`, `questionSetId`, `questionId`,
  `type` (`'DEFAULT' | 'PDP_QUESTION'`) und `newChat` akzeptiert und kein `options`-Argument hat. Wenn du das neueste
  Embed nutzt, bevorzuge die Felder `text` / `newChat`, die in beiden Varianten stabil sind.
</Note>

## getHistory()

Gibt ein `Promise` zurück, das mit dem aktuellen Chat-Verlauf-Payload aus dem Iframe aufgelöst wird. Nützlich für eigenes Tracking. Die Anfrage läuft nach einigen Sekunden ab, falls das Iframe nicht antwortet.

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

## updateMessageMetadata(metadata)

Hängt Metadaten als Schlüssel-Wert-Paare an die nächste Nutzernachricht an. Gibt `void` zurück. Ist das Iframe noch nicht bereit, werden die Metadaten zwischengespeichert und automatisch gesendet, sobald das Iframe initialisiert. Mehrere Aufrufe werden zusammengeführt.

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

**Limits und Validierung**

| Einschränkung  | Limit                                               |
| -------------- | --------------------------------------------------- |
| Max. Schlüssel | 5 Schlüssel-Wert-Paare pro Aufruf                   |
| Schlüssellänge | Max. 50 Zeichen                                     |
| Wertlänge      | Max. 100 Zeichen                                    |
| Schlüsseltyp   | Muss ein String sein                                |
| Werttyp        | String oder `null`, um einen Schlüssel zu entfernen |

**Zusammenführen und Entfernen von Schlüsseln**

* Bestehende Schlüssel können mit neuen Werten überschrieben werden.
* Schlüssel werden entfernt, indem `null` als Wert übergeben wird.
* Mehrere Aufrufe werden zusammengeführt — neue Schlüssel werden hinzugefügt, bestehende aktualisiert.

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

// Update an existing key and add a 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-Anwendungen (SPAs):** Metadaten-Schlüssel bleiben über Navigationen hinweg bestehen, weil sie im
  globalen Window-Kontext liegen. Wenn du zwischen Seiten navigierst, lösche veraltete Metadaten manuell, indem du
  `updateMessageMetadata()` mit `null`-Werten aufrufst, um ungewolltes Fortbestehen zu vermeiden.
</Warning>

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

## sendCustomPdpQuestion(questionSetId)

Öffnet den Chat und löst den eigenen Produktfragen-Flow für ein bestimmtes Fragenset aus. Gibt ein `Promise` zurück. Diese Methode steht hinter dem „Frag etwas anderes"-Button des Produktfragen-Widgets.

```js theme={null}
await window.homieBot.sendCustomPdpQuestion('pdp-questions-set-123');
```

<Warning>
  Diese Methode ist auf `window.homieBot` verfügbar, ist aber primär für das eingebaute Produktfragen-Widget gedacht.
  Nutze sie nur, wenn du einen eigenen Einstiegspunkt für Produktfragen rendern willst.
</Warning>

## trackPdpQuestionsView(element, questionSetId)

Meldet einen qualifizierten View (Impression) für selbst gerenderte Produktfragen. Gibt `void` zurück. Nutze diese Methode, wenn dein Shop die Produktfragen über die [REST API](/de/api-reference/backend/pdp-questions/get-pdp-questions) lädt und mit eigenem Markup rendert — sie wendet dieselben Sichtbarkeitsregeln an wie das eingebaute Rendering, damit deine Views und Click-Through-Rates in den Analytics der Plattform vergleichbar bleiben:

* zählt nur, wenn das Element mindestens 1 Sekunde lang zu mindestens 50 % im Viewport sichtbar war
* zählt höchstens einmal pro Seitenbesuch (pro Produkt-URL)
* kann bei Framework-Re-Renders gefahrlos erneut aufgerufen werden — eine laufende Messung wird auf dem neuen Element neu gestartet, ein bereits gezählter Besuch feuert nie doppelt

Rufe sie einmal direkt nach dem Rendern deines Fragen-Elements auf:

```js theme={null}
// You fetched { questionSetId, questions } from the product questions API
// and rendered your own UI into `container`.
window.homieBot.trackPdpQuestionsView(container, questionSetId);
```

| Parameter       | Typ     | Beschreibung                                         |
| --------------- | ------- | ---------------------------------------------------- |
| `element`       | Element | Das DOM-Element mit deinen gerenderten Fragen.       |
| `questionSetId` | string  | Die vom Fragen-Endpoint zurückgegebene Fragenset-ID. |

<Note>
  Views sind der Nenner der Click-Through-Rate. Wenn du Fragen selbst renderst und diese Methode nie aufrufst, zeigen
  deine Produktseiten in den Analytics Klicks, aber keine Views.
</Note>