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.

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.

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 und der FAB (Floating Action Button) sichtbar 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