MagicAI Chat-Widget per JavaScript steuern

In diesem Artikel lernst du, wie du das MagicAI Chat-Widget auf deiner Website per JavaScript steuerst, welche Optionen es gibt, wie sie mit der Chatkonfiguration zusammenspielen und welche Limits gelten.

Inhalt

• Schnellanleitung
• Voraussetzungen
• Einstiegsbeispiel
• Konfigurationsoptionen
• Zusammenspiel mit der Chatkonfiguration
• Limits und Besonderheiten
• Praxisbeispiele
• Verwandte Artikel

Schnellanleitung

1. Binde das Chat-Widget mit dem Code aus der Karte Code-Vorschau auf deiner Website ein.
2. Rufe in deinem eigenen Skript window.SpaChatWidget?.configure({ ... }) nur mit den Optionen auf, die du ändern willst.
3. Prüfe den Rückgabewert: true heißt, die Werte wurden übernommen, false heißt, es wurde nichts übernommen.
4. Mit window.SpaChatWidget?.open() und window.SpaChatWidget?.close() öffnest oder schließt du den Chat.

Voraussetzungen

• Veröffentlichte Chatkonfiguration: Eine Konfiguration im Entwurfsmodus liefert keinen Code zum Einbinden.
• Widget eingebunden: Der Code aus der Karte Code-Vorschau ist auf deiner Website eingebunden. Er lädt das Widget-Skript mit der Kennung deiner Chatkonfiguration. Wie du ihn einbindest und welche technischen Voraussetzungen gelten, erfährst du im Artikel MagicAI Chat einrichten.
• Dein Skript läuft nach dem Widget: Die Methoden unten stehen erst zur Verfügung, wenn das Widget-Skript geladen ist. Läuft dein Code früher, wird der Aufruf übersprungen und es ändert sich nichts.

Einstiegsbeispiel

Sobald das Widget-Skript geladen ist, kann deine Seite das Objekt window.SpaChatWidget nutzen. Es bietet drei Methoden: configure(), open() und close().

window.SpaChatWidget?.configure({
  teaserMessage: 'Wie können wir dir helfen?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'Mitgliedschaften ansehen', message: 'Welche Mitgliedschaften gibt es?' }
  ]
});

window.SpaChatWidget?.open();  // Chat öffnen
window.SpaChatWidget?.close(); // Chat schließen

Der Operator ?. macht den Aufruf sicher: Ist das Widget noch nicht geladen, wird der Aufruf übersprungen, statt einen Skriptfehler auszulösen.

configure() gibt true zurück, wenn die Werte übernommen werden, und false, wenn sie ungültig sind. Mit dem Rückgabewert kannst du deinen Aufruf prüfen:

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('Das Chat-Widget hat die Einstellungen abgelehnt.');
}

Ist das Widget noch nicht geladen, wird der Aufruf übersprungen und der Rückgabewert ist undefined statt true oder false.

Konfigurationsoptionen

Alle Optionen sind optional. Übergib nur die, die du ändern willst.

Klickt eine Besucherin oder ein Besucher auf einen Vorschlag, startet der Chat mit dem Text aus message als erster Nachricht. Hat ein Eintrag keine message, wird stattdessen der buttonText gesendet.

Zusammenspiel mit der Chatkonfiguration

Ohne Einstellungen von deiner Website nutzt das Widget den Teaser und die Vorschläge aus der Chatkonfiguration. Diese pflegst du ohne Code in der Chatkonfiguration unter Einstellungen / MagicAI / Chat, Karte Allgemeine Angaben.

• Inhalte werden ersetzt: teaserMessage ersetzt den konfigurierten Teaser-Text, suggestions ersetzt die komplette konfigurierte Vorschlagsliste.
• Sichtbarkeit steuerst du getrennt: visible, teaserVisible, suggestionsVisible und startscreenSuggestionsVisible wirken unabhängig vom Inhalt. Übergibst du keine Sichtbarkeitsoption, zeigt das Widget, was die Chatkonfiguration vorgibt.
• Sichtbar braucht Inhalt: Eine Sichtbarkeitsoption auf true erzeugt keinen Teaser-Text und keine Vorschläge. Liefern weder deine Website noch die Chatkonfiguration welche, wird nichts angezeigt.
• Aufrufe werden zusammengeführt: Ein späterer Aufruf behält die Optionen früherer Aufrufe und ändert nur die Optionen, die er selbst enthält. Ein Aufruf nur mit teaserVisible: false lässt zum Beispiel eine vorher gesetzte teaserMessage bestehen.
• Verzögerung: Teaser-Text und Vorschläge erscheinen etwa drei Sekunden, nachdem das Widget geladen ist, neben der Chat-Schaltfläche.
• Weggeklickter Teaser: Schließt eine Besucherin oder ein Besucher den Teaser, bleiben Teaser und Vorschläge für den Rest dieser Browsersitzung ausgeblendet. Ein Aufruf mit visible: true, teaserVisible: true oder suggestionsVisible: true hebt das auf und zeigt sie wieder an. Damit übergehst du also auch die Entscheidung der Besucherin oder des Besuchers.

Limits und Besonderheiten

• Teaser-Text: max. 500 Zeichen.
• Vorschläge: max. 3, jeder Schaltflächentext max. 40 Zeichen und nicht leer, jede Nachricht max. 500 Zeichen.
• Ungültiger Aufruf: configure() gibt false zurück, wenn ein Wert den falschen Typ hat, ein Limit überschritten ist oder das Argument kein einfaches Objekt ist. Dann wird keiner der Werte aus diesem Aufruf übernommen.
• Übernommen heißt nicht geladen: Der Rückgabewert true bestätigt nur, dass die Werte gültig sind. Er bedeutet nicht, dass der Chat fertig geladen ist oder eine Unterhaltung begonnen hat.
• Ausblenden schließt nicht: visible: false blendet die Chat-Schaltfläche aus, schließt aber keinen Chat, der bereits offen ist. Zum Schließen nutzt du close() oder isOpen: false.

Praxisbeispiele

Die folgenden Codeausschnitte sind Beispiele. Passe Texte und Element-IDs an deine Website an und führe den Code aus, nachdem das Widget-Skript geladen ist.

Beispiel: Chat über eine eigene Schaltfläche öffnen

<button type="button" id="open-chat">Chatte mit uns</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Beispiel: seitenspezifischen Teaser anzeigen

Auf einer Seite zu Kursen kannst du den konfigurierten Teaser-Text zum Beispiel durch einen passenden ersetzen:

window.SpaChatWidget?.configure({
  teaserMessage: 'Fragen zu unseren Kursen? Frag uns einfach.',
  teaserVisible: true
});

Beispiel: Chat-Schaltfläche auf einer Seite ausblenden

Auf einer Seite, auf der die Chat-Schaltfläche nicht erscheinen soll, zum Beispiel im Bestellvorgang:

window.SpaChatWidget?.configure({ visible: false });

Führe den Aufruf auf jeder Seite aus, auf der die Einstellung gelten soll.

Verwandte Artikel

• MagicAI Chat einrichten

Hinweis: Dieser Artikel wurde mit Unterstützung von künstlicher Intelligenz erstellt und redaktionell geprüft.