Chat-Widget Steuerung und technische Anpassungen
Position, Sichtbarkeit und Verhalten des Chat-Widgets über die API steuern
Zusätzlich zu den verfügbaren allgemeinen Widget-Einstellungen und Designanpassungen im moinAI Hub können auch technische Anpassungen an der Darstellung und am Verhalten des Chat-Widgets vorgenommen werden.
Das Chat-Widget bietet eine Javascript API-Funktion, über die weitere Steuerungsoptionen zur Verfügung stehen. Diese sind in der technischen Dokumentation der Widget-API beschrieben.
Die hier beschriebenen Anpassungen werden nicht im moinAI Hub vorgenommen, sondern im Quellcode der eigenen Webseite. Für die Umsetzung empfiehlt sich die Abstimmung mit dem eigenen Entwicklungsteam oder der IT-Abteilung. Die Einstellungen, die sich ohne Code vornehmen lassen, sind im Artikel Chat-Widget Einstellungen beschrieben.
Für alle Code-Beispiele in diesem Artikel gilt:
- Die Befehle werden innerhalb der Funktion
window.chatWidgetReadyaufgerufen. Diese Funktion wird ausgeführt, sobald das Chat-Widget bereit ist. - Der Code-Block mit
window.chatWidgetReadymuss im Quellcode der Webseite vor dem Einbindungscode des Chat-Widgets stehen. Steht er dahinter, wird die Funktion nicht ausgeführt. - Diese Schreibweise funktioniert auch bei einer Einbindung über den Google Tag Manager.
- Widget-Position ändern
- Widget-Position bei manuellem Teaser ändern
- Widget öffnen und schließen
- Widget aus- und einblenden
1. Widget-Position ändern
Damit das Chat-Widget keine anderen Elemente überdeckt (z. B. einen Scroll-to-top-Button oder ein Kontakt-Widget), lässt es sich im Button Modus bereits ohne Code im Hub links oder rechts platzieren. Ebenfalls im Hub wird festgelegt, ob das Widget im Button Modus oder im Input-Bar Modus erscheint. Reicht die Ausrichtung links oder rechts nicht aus, lässt sich die Position im Button Modus per Code genauer festlegen. Sie gilt dann für das geschlossene und das geöffnete Chat-Widget. Anders als im Input-Bar Modus können Nutzer:innen das Widget im Button Modus nicht selbst verschieben.
<script>
window.chatWidgetReady = function () {
window.moin.setPosition({ bottom: 24, right: 32, unit: 'px' });
};
</script>
bottomlegt den Abstand vom unteren Rand fest.rightlegt den Abstand vom seitlichen Rand fest. Ist das Chat-Widget im Hub auf links eingestellt, gilt dieser Wert als Abstand vom linken Rand. Ob das Chat-Widget links oder rechts steht, wird ausschließlich im Hub festgelegt.unitbestimmt die Einheit. Möglich sind alle gültigen CSS-Einheiten, z. B.px,rem,vhoder%.
Alle Parameter und ihre erlaubten Werte sind im Abschnitt setPosition der API-Dokumentation beschrieben.
2. Widget-Position bei manuellem Teaser ändern
Dieses Kapitel betrifft nur den manuellen Teaser, der per Code auf der Webseite eingebunden wird. Teaser, die im Hub unter Widget & Teaser > Teaser angelegt werden, passen ihre Position automatisch an das Chat-Widget an. Sie brauchen keine eigene Anpassung. Mehr dazu im Artikel Teaser: Einrichtung und Anpassungen.
Code-Beispiel und Erklärung anzeigen
Der folgende Code enthält sowohl den Teaser als auch die Definition der Position. Die beiden Werte bottom: 100 und right: 100 geben den Abstand von unten und von rechts an. Sie definieren die Position auf der jeweiligen Achse und akzeptieren alle gültigen CSS-Einheiten, auch Prozentangaben.
Die Werte bei intent sind die technischen Namen der Themen oder Formulare, die über die Schnellantworten des Teasers aufgerufen werden. Der technische Name lässt sich im Hub aus der URL des geöffneten Themas oder Formulars ablesen: Er steht dort zwischen dem zweiten Schrägstrich und dem Fragezeichen. Der Artikel Interaktion zwischen Webseite und Chat-Widget erweitern beschreibt das ausführlich.
<script>
window.chatWidgetReady = function () {
window.moin.teaser({
showTeaser: true,
showAvatar: true,
message: 'Wie kann ich dir helfen?',
quickActions: [
{
text: 'Frage stellen',
intent: 'start'
},
{
text: 'Beispielthema',
intent: 'faq_beispielthema'
}
]
});
window.moin.setPosition({ bottom: 100, right: 100, unit: 'px' });
};
</script>
3. Widget öffnen und schließen
Das Öffnen und Schließen des Chat-Widgets kann durch Regeln oder Buttons auf der Webseite gesteuert werden. Die Angaben dazu finden sich im Abschnitt zum Öffnen des Widgets. Zum Beispiel kann das Chat-Widget automatisch beim Aufrufen einer bestimmten Unterseite, nach dem Scrollen zum Seitenende oder nach dem Klick auf einen Webseiten-Button geöffnet werden.
- Öffnen:
window.moin.open()– Beschreibung im Abschnitt open - Schließen:
window.moin.close()– Beschreibung im Abschnitt close - Umschalten:
window.moin.toggle()öffnet ein geschlossenes und schließt ein geöffnetes Chat-Widget. Beschreibung im Abschnitt toggle
Soll sich das Chat-Widget nach einem Klick auf einen Webseiten-Button öffnen und direkt mit einer Anfrage, einem Thema oder einem Formular starten, eignet sich die Funktion startWith(). Wie das funktioniert, beschreibt der Artikel Interaktion zwischen Webseite und Chat-Widget erweitern, inklusive Anwendungsbeispielen und einer Live-Demo.
4. Widget aus- und einblenden
Im Abschnitt zum Aus- und Einblenden der technischen Dokumentation sind die Befehle hinterlegt, mit denen das gesamte Chat-Widget einschließlich des Chat-Widget-Symbols auf der Webseite ausgeblendet oder eingeblendet werden kann.
- Ausblenden
Der folgende JavaScript-Befehl blendet das Chat-Widget aus:window.moin.hideWidget(); - Einblenden
Mit den folgenden Befehlen wird es wieder angezeigt und geöffnet, z. B. nachdem ein Button angeklickt wurde:window.moin.showWidget();window.moin.open();
<script>
// Die Funktion „chatWidgetReady“ wird aufgerufen, sobald das Chat-Widget bereit ist
// und auf die Client-API zugegriffen werden kann.
// Dieser Code-Block muss vor dem Einbindungscode des Chat-Widgets stehen.
window.chatWidgetReady = function () {
// Beide Funktionen können mehrfach aufgerufen werden und tun nichts,
// wenn sich das Widget bereits im gewünschten Zustand befindet.
// Blendet das Widget aus, wenn es sichtbar ist:
window.moin.hideWidget();
// Zeigt das Widget an, wenn es ausgeblendet ist:
window.moin.showWidget();
};
</script>