Contao-Chatbot installieren: Anleitung mit Assistent

Voraussetzungen

Contao 4.13 oder 5.x und PHP 8.0 oder neuer. Getestet mit Contao 4.13 (PHP 8.1) und 5.7 (PHP 8.3).
Die Installation läuft im prod-Environment, zumindest für den Trainingslauf.
Die Website kann ihre eigene Domain erreichen (für das Training per Klick und die zeitgesteuerten Inhalte).
HTTPS, wenn Du die Spracheingabe nutzen willst.

1 Konto, Projekt und API-Schlüssel

Öffne das Portal, registriere Dich und bestätige Deine E-Mail-Adresse.
Lege ein Projekt an. Jede Website bekommt ihr eigenes Projekt und damit ihre eigene, getrennte Wissensbasis.
Wechsle im Projekt zu API-Keys und erzeuge einen Schlüssel.
Kopiere den Schlüssel sofort. Er wird nur einmal vollständig angezeigt.

2 Erweiterung installieren

Variante A: Contao Manager

Öffne den Contao Manager und suche unter Pakete nach bluebranch/chatbot.
Füge das Paket hinzu und wende die Änderungen an.

Variante B: Composer

Konsolecomposer require bluebranch/chatbot
php vendor/bin/contao-console contao:migrate

Rufe danach das Backend einmal auf (oder führe Datenbank aktualisieren aus), damit die neuen Tabellen und Felder angelegt werden. Im Backend erscheint der Bereich BlueBranch Chatbot.

Als Webserver-Benutzer ausführen. Konsolenbefehle gehören unter dem Benutzer des Webservers ausgeführt, meist www-data. Als root gestartet gehört das neu angelegte Cache-Verzeichnis hinterher root, der Webserver kann nicht mehr hineinschreiben, und die Website antwortet nur noch mit 500, ohne Eintrag im Anwendungslog. Über den Contao Manager kann das nicht passieren.

3 Der Assistent „Erste Schritte“

Unter BlueBranch Chatbot → Erste Schritte findest Du den schnellsten Weg. Der Bereich steht Administratoren offen und lässt sich über die Backend-Module in den Benutzer- und Gruppenrechten freigeben.

Zugang verbinden. Schlüssel einfügen. Die Verbindung wird sofort geprüft (Tarif, Verbrauch, Spracheingabe). Ein abgelehnter Schlüssel wird nicht übernommen, ein bisheriger bleibt erhalten. Gespeichert wird er am Startpunkt der Website im Seitenbaum. Bei mehreren Websites wählst Du oben die Website.
Inhalte trainieren. Der Assistent zeigt, wie viele Seiten und Zusatzinhalte trainiert sind. Jetzt trainieren ruft die Seiten der Website nacheinander ab (Fortschrittsbalken), Contao indiziert sie und übergibt sie an die API. Alles neu trainieren setzt den Stand zurück.
Chat anzeigen. Name und Akzentfarbe festlegen, dann Chat auf allen Seiten anzeigen. Das Widget erscheint ohne Layout- und Modul-Arbeit auf jeder Seite. Einzelne Seiten nimmst Du mit Chat auf dieser Seite ausblenden in den Seiteneinstellungen heraus. Ein Widget, das schon im Layout oder Artikel steht, wird nicht doppelt eingesetzt.

Optional folgen Ausprobieren (Testfrage direkt im Backend) und Feinschliff (Spracheingabe und Feedback als Voreinstellung). Zusätzlich prüft der Assistent Deine Projekt-Templates und nennt, welche veraltet sind.

4 Alternative: von Hand einrichten

Schlüssel: Seitenstruktur → Startpunkt der Website bearbeiten → Chatbot API-Key. Ein hinterlegter Schlüssel steht nie im Formular, nur als Platzhalter. Platzhalter stehen lassen behält ihn, leeren löscht ihn, etwas anderes gilt als neuer Schlüssel. Mehrere Websites bekommen je einen eigenen Schlüssel.
Training: System → Suchindex neu aufbauen. Sobald der Crawler läuft, wird jede indizierte Seite an die API übergeben. Was nicht im Suchindex steht, kennt der Chatbot nicht.
Module: siehe Schritt 5.

Es wird nichts trainiert? Läuft die Installation im dev-Environment, hängt Symfony an jede Antwort einen X-Robots-Tag: noindex-Header. Der Contao-Crawler überspringt daraufhin sämtliche Seiten. Setze für den Trainingslauf APP_ENV=prod.

5 Module einbinden

Wer lieber selbst platziert, findet unter Themes → Frontend-Module drei Module und bindet sie wie gewohnt in Layout oder Artikel ein:

Modul	Zweck
Chatbot Widget	Aufklappbarer Chat-Button, standardmäßig unten rechts
Chatbot KI-Suche	Zusammenfassende KI-Antwort über der Trefferliste der Suche; mit dem Template `mod_chatbot_generate_search_full` mit eigenem Suchfeld
Chatbot Frage	Eingabefeld für Startseiten, Antwort samt Quellen direkt darunter

Bei Chatbot Frage und Chatbot KI-Suche hinterlegst Du unter Getippte Fragen beliebig viele Texte, die Zeichen für Zeichen als Platzhalter ins Feld geschrieben werden. Wer in seinem System „Bewegung reduzieren“ eingestellt hat, sieht die erste Frage unbewegt stehen.

6 Antworten prüfen

Stelle im Assistenten eine Testfrage. Die Antwort kommt samt Quellen.
Unter BlueBranch Chatbot → Trainierte Inhalte siehst Du je Website, was die Wissensbasis enthält: Titel, URL, Anzahl der Abschnitte, Sprache und Trainingsdatum. Dort lassen sich Einträge löschen. Oben stehen Deine Nutzungsstufe und der Verbrauch im laufenden Monat.
Rufe die Website in einem Privatfenster auf und stelle dem Chat eine Frage, deren Antwort Du kennst.

Einstellungen und Aussehen

Unter System → Einstellungen setzt Du Vorgaben für alle Chat-Widgets, die jedes Modul einzeln überschreiben kann:

Name des Chatbots, Akzentfarbe (Farbwähler), eigenes Icon als SVG
Standard-Begrüßung und Standard-Vorschläge als Pillen
„Inhalt zusammenfassen“-Pille und Datenschutz-Hinweis ausblenden
Spracheingabe im Chat-Widget anbieten (standardmäßig aus), je Modul auf An oder Aus stellbar
Fragen und Antworten speichern (Aufbewahrung 180 Tage, 0 = unbegrenzt) sowie Feedback abfragen
Intervall der automatischen Bereinigung: stündlich, alle 6 Stunden, täglich oder wöchentlich

Das Design lässt sich ohne Eingriff in die Erweiterung über CSS-Variablen anpassen:

CSS.chatbot-widget,
.chatbot-ask-container,
.chatbot-generate-search-container {
    --chatbot-widget-accent: #f47c00;          /* Hauptfarbe, Töne und Schein leiten sich ab */
    --chatbot-widget-accent-contrast: #1a1a1a; /* Schriftfarbe auf der Hauptfarbe */
    --chatbot-widget-radius: 12px;
    --chatbot-widget-font: "Inter", sans-serif;
}

Wer das Styling komplett selbst übernimmt, setzt im Modul Kein Standard-Styling. Der KI-Hinweis: Nenne den Chat ausdrücklich „KI-Assistent“ und weise in der Begrüßung darauf hin. Warum, steht im Beitrag AI Act und Chatbots.

Inhalte ausschließen

In den Seiteneinstellungen steht neben Von der Suche ausschließen (ab Contao 5.6: Suchindexierung) das Feld Aus den KI-Antworten ausschließen. Beide entscheiden unabhängig voneinander, ob eine Seite als Quelle dient, für zwei verschiedene Suchen. Eine Kontaktseite kann so in der Volltextsuche stehen und trotzdem aus den Chatbot-Antworten herausbleiben. Die Einstellung vererbt sich auf alle Unterseiten, und die betroffenen Seiten verlassen sofort die Wissensbasis.

Die Inhaltselemente Suchindex: Bereich ausnehmen (indexer::stop/continue) werden für die KI-Wissensbasis bewusst ignoriert, damit auch Nachrichtenlisten und andere dynamische Bereiche beantwortbar bleiben.

Zusatzinhalte, Fragen und Feedback

BlueBranch Chatbot → Zusatzinhalte nimmt Texte und Dateien (TXT, MD, CSV, PDF, DOCX, ODT, HTML, bis 20 MB) ohne eigene Seite auf. Der Text wird auf Deinem Server ausgelesen, an die API gehen nur Text und keine URL. BlueBranch Chatbot → Fragen & Feedback listet gespeicherte Fragen mit Filtern, Löschen und CSV-Export (UTF-8, Semikolon, Formeln entschärft).

Fehlersuche

Der Chat antwortet nicht („Bitte laden Sie die Seite neu“)

Ein eigenes Template unter templates/mod_chatbot_*.html5 ersetzt das der Erweiterung und stammt aus einer Version vor 1.3.0. Dort fehlt die Signatur von Seite und Modul, die seitdem Pflicht ist. Lösche Deine Kopie oder kopiere das Template neu aus vendor/bluebranch/chatbot/src/Resources/contao/templates/ und wende Deine Änderungen erneut an. Templates ab 1.3.0 laufen weiter, aber ohne neue Funktionen wie das Mikrofon.

Die Antwort kommt auf einmal statt Wort für Wort

Ein Reverse Proxy puffert die Antwort. Bei nginx schaltest Du proxy_buffering off für die Routen unter /bluebranch/chatbot/ ab.

Alle Besucher teilen sich ein Limit

Hinter einem Proxy muss dieser unter trusted_proxies eingetragen sein, sonst kommen alle Besucher mit derselben Adresse an.

Das Mikrofon fehlt

Alle drei Bedingungen müssen zutreffen: Das Modul erlaubt die Spracheingabe, die API hat die Spracherkennung für den Zugang eingerichtet, und die Seite läuft über HTTPS in einem Browser, der aufnehmen kann.

„Bitte später erneut versuchen“

HTTP 429 bedeutet: Minutenlimit (rate_limit) oder Monatskontingent (monthly_quota) erreicht. Besucher lesen nur einen neutralen Hinweis, der Grund steht im Log. HTTP 403 mit project_paused zeigt „Der Chat steht im Moment nicht zur Verfügung“.

Aktualisieren

Nach dem Einspielen einer neuen Fassung sind zwei Schritte nötig, sonst ändert sich nichts:

System-Wartung → Anwendungscache leeren
System-Wartung → Datenbank aktualisieren

Konsolecomposer update bluebranch/chatbot
php vendor/bin/contao-console cache:clear --env=prod
php vendor/bin/contao-console contao:migrate

Ohne Schritt 1 sieht es aus, als sei nichts angekommen: Contao kompiliert seinen Dienst-Container nach var/cache/prod/ und liest ihn danach nur noch. Eine neu hochgeladene Klasse existiert für die Anwendung nicht, Callbacks werden nicht registriert, und es gibt keine Fehlermeldung. Ob eine Klasse angekommen ist, zeigt debug:container ApiKeyFieldListener --env=prod: In der Zeile Tags muss contao.callback stehen. Leere nach dem Update außerdem den Seiten-Cache.

Zum Versionslog

Datenschutz auf Deiner Website

Der API-Schlüssel bleibt auf Deinem Server, der Browser spricht nur mit Contao. Trotzdem gehört der Chatbot in Deine Datenschutzerklärung, und mit uns brauchst Du einen Auftragsverarbeitungsvertrag. Das Wichtigste dazu steht auf der Seite DSGVO & AVV, Textbausteine im Beitrag Datenschutzerklärung für den Chatbot. Die Spracheingabe gehört ausdrücklich dazu, wenn Du sie einschaltest.

Contao-Chatbot installieren und einrichten