Methoden - homie Documentation

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.

Sichere dich immer dagegen ab, dass window.homieBot beim Seitenaufruf noch undefined ist. Siehe die Beispiele für ein Wait-for-Ready-Muster.

open()

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

window.homieBot.open();

close()

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

window.homieBot.close();

toggle()

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

window.homieBot.toggle();

isOpen()

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

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.

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.

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

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.

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.

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.

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.

// 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
});

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.

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

await window.homieBot.sendCustomPdpQuestion('pdp-questions-set-123');

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.

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 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:

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

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.

​open()

​close()

​toggle()

​isOpen()

​isReady()

​sendMessage(input, options?)

​getHistory()

​updateMessageMetadata(metadata)

​sendCustomPdpQuestion(questionSetId)

​trackPdpQuestionsView(element, questionSetId)

open()

close()

toggle()

isOpen()

isReady()

sendMessage(input, options?)

getHistory()

updateMessageMetadata(metadata)

sendCustomPdpQuestion(questionSetId)

trackPdpQuestionsView(element, questionSetId)