Einführung - homie Documentation

Die Client-API ist eine browserseitige JavaScript-Schnittstelle, die vom homie-Embed-Skript bereitgestellt wird. Sobald das Skript geladen ist, steht ein globales window.homieBot-Objekt zur Verfügung. Damit öffnest oder schließt du das Widget, prüfst seinen Zustand, sendest programmatisch Nachrichten, hängst Metadaten an und liest den Chat-Verlauf — alles aus deinem eigenen Seitencode.

Diese Seite dokumentiert die clientseitige Browser-API des Embed-Skripts. Für serverseitige REST-Endpunkte siehe die REST API.

Embed-Skript einbinden

Füge das Embed-Skript zu deiner Seite hinzu. Styling und Verhalten werden in der homie Plattform verwaltet und vom Embed automatisch geladen.

<script
  src="https://cdn.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  defer
></script>

Plattformspezifische Installationsschritte findest du in der Installations-Übersicht.

Voraussetzungen

Das Skript muss auf deiner Seite eingebunden sein.
chatbotId muss gesetzt sein (am Script-Tag oder über window.homieBotConfig).

Alle Script-Attribute und globalen Konfigurationsobjekte findest du unter Konfiguration.

Wann die API verfügbar ist

Das window.homieBot-Objekt existiert erst, nachdem das Embed initialisiert wurde. Geh nicht davon aus, dass es beim Seitenaufruf schon vorhanden ist.

Wenn du window.homieBot direkt beim Seitenaufruf liest, kann es undefined sein. Höre auf das Event homiebot:api-ready oder nutze den waitForHomie()-Polling-Fallback aus den Beispielen.

Das Embed löst Browser-Events aus, sobald es die jeweilige Lebenszyklus-Phase erreicht:

Event	Wann
`homiebot:api-ready`	`window.homieBot` ist verfügbar
`homiebot:assistant-ready`	Chat-Iframe ist bereit für `sendMessage` / `getHistory`
`homiebot:opened`	Chat-Widget wurde geöffnet
`homiebot:closed`	Chat-Widget wurde geschlossen

Jedes Event enthält { chatbotId } in event.detail. Details findest du unter Events.

Methoden im Überblick

Methode	Zweck
`open()`	Chat öffnen
`close()`	Chat schließen
`toggle()`	Zwischen offen/geschlossen wechseln
`isOpen()`	Prüfen, ob das Widget offen ist
`isReady()`	Prüfen, ob das Iframe für Nachrichten bereit ist
`sendMessage(input, options?)`	Eine Nachricht in den Chat einfügen
`getHistory()`	Aktuellen Chat-Verlauf lesen
`updateMessageMetadata(metadata)`	Metadaten an die nächste Nachricht anhängen
`sendCustomPdpQuestion(questionSetId)`	Den eigenen Produktfragen-Flow öffnen
`trackPdpQuestionsView(element, questionSetId)`	Einen View für selbst gerenderte Produktfragen melden

Die vollständige Referenz findest du unter Methoden.

Client-API entdecken

Konfiguration

Script-Attribute, globale Konfigurationsobjekte, Sprach- und Shopify-Markt-Auflösung.

Methoden

Vollständige Referenz für jede Methode auf window.homieBot.

Events

Vom Embed ausgelöste Browser-Events für Lebenszyklus und Interaktion.

Beispiele

Praktische Rezepte zum Öffnen, Senden und Tracken.

Fehlerbehebung

Lösungen für die häufigsten Integrationsprobleme.

​Embed-Skript einbinden

​Voraussetzungen

​Wann die API verfügbar ist

​Methoden im Überblick

​Client-API entdecken

Konfiguration

Methoden

Events

Beispiele

Fehlerbehebung

Embed-Skript einbinden

Voraussetzungen

Wann die API verfügbar ist

Methoden im Überblick

Client-API entdecken