Zum Hauptinhalt springen

Integration in eine Webseite

Der Website-Messenger von Bubble Chat lässt sich einfach und schnell auf jeder Webseite einbinden. Die Integration erfolgt über ein Script-Tag und erfordert keine komplexen Setup-Schritte.

Zwei Integrationsvarianten für die Anzeige​

Grundsätzlich gibt es zwei Arten, wie der Chat auf einer Webseite angezeigt und geöffnet werden kann:

  1. Standard-Variante mit FAB (Floating Action Button): Der Messenger blendet unten auf der Webseite ein Chat-Icon ein. Klickt der Benutzer auf diesen Button, öffnet sich das Chatfenster.

  2. Gesteuerte Variante durch die Webseite: Die Webseite übernimmt selbst die Steuerung, wann das Chatfenster angezeigt wird. So kann z. B. ein eigenes Eingabefeld wie "Frage unsere KI ..." verwendet werden. Sendet der Benutzer das Formular ab, kann die Webseite das Chatfenster öffnen und die eingegebene Frage direkt an den Chatbot übergeben.

Für diese zweite Variante nutzt der Webseitenersteller die JavaScript API von Bubble Chat. Typischerweise wird der FAB dabei mit data-fab-visible="false" ausgeblendet und der Chat über API-Aufrufe gesteuert.

Script-Tag Integration​

Die Integration des Chatbots erfolgt durch das Einbinden eines Script-Tags im HTML-Code deiner Webseite:

<script
  id="chatbot"
  data-server="https://my-chatbot.bubble-chat.ch"
  data-expand-at-start="all"
  data-link-handling="default"
  defer
  src="https://my-chatbot.bubble-chat.ch/webclient/embed/bundle.js"
></script>

Wichtiger Sicherheitshinweis​

Damit die Integration funktioniert, muss die Domain deiner Webseite in der Server-seitigen Konfiguration unter allowedEmbedOrigins hinterlegt sein. Kontaktiere dein Bubble Chat Team, um deine Domain freizuschalten.

Konfigurationsattribute​

data-server (erforderlich)​

Die vollständige URL zum Chatbot-Server.

Beispiel:

data-server="https://my-chatbot.bubble-chat.ch"

Query-Parameter​

Beim data-server können Query-Parameter angegeben werden, um dem Chatbot bei der Integration zusätzliche Informationen mitzuteilen:

data-server="https://my-chatbot.bubble-chat.ch?systemId=123&userRole=editor"

Hinweis: Die Query-Parameter userId und sessionId sind nicht erlaubt und werden ignoriert.

data-expand-at-start (optional)​

Steuert, ob das Chatfenster beim Laden der Seite automatisch geöffnet werden soll. Die Option berücksichtigt dabei das verwendete Endgerät.

Mögliche Werte:

  • "all" - Das Chatfenster wird auf allen Geräten automatisch geöffnet
  • "desktop" - Das Chatfenster wird nur auf Desktop-Geräten (≥ 768px Bildschirmbreite) automatisch geöffnet
  • "mobile" - Das Chatfenster wird nur auf mobilen Geräten (< 768px Bildschirmbreite) automatisch geöffnet
  • nicht gesetzt (Standard) - Das Chatfenster bleibt geschlossen

Beispiel:

data-expand-at-start="desktop"

Wichtig: Das Chatfenster wird nur automatisch geöffnet, wenn der Benutzer es nicht zuvor explizit geschlossen hat. Der Fensterstatus wird in einem Cookie (bubble-chat-window-state) für 8 Stunden gespeichert.

data-fab-visible (optional)​

Steuert, ob der FAB (Floating Action Button) angezeigt wird.

Mögliche Werte:

  • "true" (Standard) - Der FAB wird angezeigt
  • "false" - Der FAB wird ausgeblendet

Wenn der FAB ausgeblendet ist, bleibt der Messenger weiterhin vollständig funktionsfähig und kann über die JavaScript API gesteuert werden (z. B. mit openChatWindow()).

Beispiel:

data-fab-visible="false"

Steuert, wie Links im Chatbot geöffnet werden.

Mögliche Werte:

  • "default" (Standard) - Links der gleichen Domain werden im selben Tab geöffnet, Links einer anderen Domain in einem neuen Tab
  • "existing-tab" - Alle Links werden im selben Tab geöffnet
  • "new-tab" - Alle Links werden in einem neuen Tab geöffnet

Beispiel:

data-link-handling="new-tab"

Design-Anpassung​

Das Aussehen des Website-Messengers kann individuell angepasst werden, um perfekt zur Corporate Identity deiner Webseite zu passen. Alle Informationen zu CSS-Anpassungen, Farben, Logos und weiteren Design-Optionen findest du im Kapitel Design-Anpassung.

JavaScript API​

Der Webclient bietet eine JavaScript API, über welche der Chat programmatisch gesteuert werden kann. Alle API-Funktionen stehen über den Namespace chatbot zur Verfügung.

Verfügbare Funktionen​

openChatWindow()​

Öffnet das Chat-Fenster.

Beispiel:

chatbot.openChatWindow();

closeChatWindow()​

Schliesst das Chat-Fenster.

Beispiel:

chatbot.closeChatWindow();

toggleChatWindow()​

Öffnet das Chatfenster wenn es geschlossen ist und schliesst es, wenn es offen ist.

Beispiel:

chatbot.toggleChatWindow();

enterGuestMessage(message)​

Sendet eine Nachricht im Namen des Gastes an den Chatbot.

Parameter:

  • message (String) - Die zu sendende Nachricht

Beispiel:

chatbot.enterGuestMessage("Hallo Welt");

triggerStory(intent)​

Gibt den Befehl, eine Story (Intent) auszuführen.

Parameter:

  • intent (String) - Der Name des auszuführenden Intents

Beispiel:

chatbot.triggerStory("GET_STARTED");

isChatbotLoaded()​

Gibt true zurück, wenn der Chatbot geladen ist.

Beispiel:

const isLoaded = chatbot.isChatbotLoaded();
if (isLoaded) {
  console.log("Chatbot ist bereit");
}

subscribe(event, callback)​

Erlaubt das Registrieren von Event-Handlers.

Verfügbare Events:

ON_CHAT_WINDOW_STATE_CHANGE​

Wird aufgerufen, wenn sich der Zustand des Chat-Fensters ändert (öffnen/schliessen).

Beispiel:

chatbot.subscribe("ON_CHAT_WINDOW_STATE_CHANGE", function onChange(open) {
  console.log("Chat-Fenster ist " + (open ? "offen" : "geschlossen"));
});

Vollständiges Integrationsbeispiel​

<!DOCTYPE html>
<html lang="de">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Meine Webseite mit Chatbot</title>
  </head>
  <body>
    <h1>Willkommen auf meiner Webseite</h1>

    <!-- Chatbot Integration -->
    <script
      id="chatbot"
      data-server="https://my-chatbot.bubble-chat.ch"
      data-expand-at-start="desktop"
      data-link-handling="default"
      defer
      src="https://my-chatbot.bubble-chat.ch/webclient/embed/bundle.js"
    ></script>

    <!-- Optional: JavaScript API verwenden -->
    <script>
      // Warten bis der Chatbot geladen ist
      window.addEventListener("load", function () {
        // Event-Handler registrieren
        if (typeof chatbot !== "undefined") {
          chatbot.subscribe("ON_CHAT_WINDOW_STATE_CHANGE", function (open) {
            console.log("Chat ist jetzt " + (open ? "offen" : "geschlossen"));
          });
        }
      });

      // Chatbot via Button öffnen
      function openChat() {
        if (typeof chatbot !== "undefined") {
          chatbot.openChatWindow();
        }
      }
    </script>

    <!-- Optional: Custom Button zum Öffnen des Chats -->
    <button onclick="openChat()">Chat mit uns!</button>
  </body>
</html>

Troubleshooting​

Der Chatbot wird nicht angezeigt​

  • Überprüfe, ob die Domain deiner Webseite in allowedEmbedOrigins konfiguriert ist
  • Kontrolliere die Browser-Konsole auf Fehlermeldungen
  • Stelle sicher, dass das Script-Tag das Attribut defer enthält

Das Chatfenster öffnet sich nicht automatisch​

  • Prüfe, ob der Benutzer das Chatfenster zuvor manuell geschlossen hat (Cookie-Speicherung)
  • Überprüfe das Attribut data-expand-at-start
  • Lösche testweise die Cookies der Webseite

JavaScript API funktioniert nicht​

  • Stelle sicher, dass der Chatbot vollständig geladen ist, bevor du API-Funktionen aufrufst
  • Verwende chatbot.isChatbotLoaded() um zu prüfen, ob die API verfügbar ist
  • Überprüfe die Browser-Konsole auf JavaScript-Fehler