Joomla-Anleitung

FirstBot-Widget in Ihre Joomla-Website einbinden

Getestet mit Joomla 3.x, 4.x und 5.x · Funktioniert mit allen gängigen Templates

Inhalt

Ihr persönlicher Code-Schnipsel
Methode 1: Custom HTML-Modul (empfohlen)
Methode 2: Template index.php
Methode 3: System-Plugin (Joomla 4/5)
Widget testen
Häufige Fragen & Probleme

★ Ihr persönlicher Code-Schnipsel

Wenn Sie sich einloggen, wird Ihr persönlicher API-Key hier automatisch eingesetzt.

            
<script>
  window.chatBotId = 'IHR-API-KEY';
</script>
<script src="https://firstbot.de/chatbot.js" defer></script>
        

1 Methode 1: Custom HTML-Modul

★ Empfohlen – kein Eingriff in Template-Dateien

Joomla erlaubt es, beliebigen HTML- und JavaScript-Code über ein „Custom HTML"-Modul einzubinden. Das Modul wird in der Position debug (oder footer) platziert und auf allen Seiten angezeigt.

Schritt 1 – Modul anlegen

Loggen Sie sich im Joomla-Backend ein.
Gehen Sie zu Erweiterungen → Module (Joomla 3) bzw. Content → Site-Module (Joomla 4/5).
Klicken Sie oben auf „Neu".
Wählen Sie den Typ „Benutzerdefiniertes HTML" (Custom HTML).

Schritt 2 – Code einfügen

Geben Sie dem Modul einen Titel, z. B. „FirstBot Widget".
Aktivieren Sie im Editor die Option „Editor deaktivieren" oder wechseln Sie in den Quellcode-Modus (HTML-Ansicht).
Fügen Sie folgenden Code in das Textfeld ein:

<script>
  window.chatBotId = 'IHR-API-KEY';
</script>
<script src="https://firstbot.de/chatbot.js" defer></script>
            

⚠ Wichtig: Wenn der WYSIWYG-Editor aktiv ist, entfernt er Script-Tags. Stellen Sie sicher, dass Sie sich im HTML/Quellcode-Modus befinden, bevor Sie den Code einfügen.

Schritt 3 – Position und Sichtbarkeit

Wählen Sie unter „Position" eine Template-Position wie debug, footer oder bottom (je nach Template).
Stellen Sie unter „Zuweisung der Menüpunkte" ein: „Auf allen Seiten".
Stellen Sie den Status auf „Veröffentlicht".
Klicken Sie auf „Speichern & Schließen".

✓ Das Modul erscheint nun auf allen Seiten. Da es nur JavaScript lädt, ist es für Besucher unsichtbar – nur der Chat-Button wird angezeigt.

2 Methode 2: Template index.php

Direkte Template-Bearbeitung

Für Nutzer, die direkten Zugriff auf das Template haben, kann der Code direkt in die index.php des aktiven Templates eingefügt werden.

⚠ Diese Änderung wird bei einem Template-Update überschrieben. Nutzen Sie ein Child-Template (in Joomla 4/5 verfügbar) oder Methode 1, um das zu vermeiden.

Schritt 1 – Template-Editor öffnen

Gehen Sie zu Erweiterungen → Templates → Templates.
Klicken Sie auf das aktive Template (z. B. Cassiopeia in Joomla 4/5).
Wählen Sie die Datei index.php im Datei-Manager.

Schritt 2 – Code einfügen

Suchen Sie nach dem schließenden </head>-Tag und fügen Sie den Code direkt davor ein:

<script>
  window.chatBotId = 'IHR-API-KEY';
</script>
<script src="https://firstbot.de/chatbot.js" defer></script>
</head>
            

Klicken Sie auf „Datei speichern".
Besuchen Sie Ihre Website – der Chat-Button sollte erscheinen.

3 Methode 3: System-Plugin (Joomla 4/5)

Für Entwickler · Joomla 4 und 5

Ein eigenes System-Plugin ist die professionellste Methode: Es injiziert den Code in den <head> und ist unabhängig vom Template.

💡 Diese Methode erfordert das manuelle Anlegen einer Plugin-Datei. Für Einsteiger empfehlen wir Methode 1 (Custom HTML-Modul).

Plugin-Datei erstellen

Erstellen Sie per FTP folgende Struktur unter /plugins/system/firstbot/:

firstbot.php

<?php
defined('_JEXEC') or die;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Factory;

class PlgSystemFirstbot extends CMSPlugin {
    public function onBeforeCompileHead() {
        $doc = Factory::getApplication()->getDocument();
        $doc->addScriptDeclaration(
            "window.chatBotId = 'IHR-API-KEY';"
        );
        $doc->addScript(
            'https://firstbot.de/chatbot.js',
            ['version' => 'auto'],
            ['type' => 'module']
        );
    }
}
            

firstbot.xml (Manifest)

<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" group="system" method="upgrade">
  <name>System – FirstBot</name>
  <version>1.0</version>
  <files>
    <filename plugin="firstbot">firstbot.php</filename>
  </files>
</extension>
            

Nach dem Hochladen via FTP: Im Backend unter Erweiterungen → Plugins das Plugin „System – FirstBot" suchen und aktivieren.

4 Widget testen

Öffnen Sie Ihre Website in einem neuen Browser-Tab.
Drücken Sie Strg+Shift+R (Windows) bzw. Cmd+Shift+R (Mac) zum Cache-Leeren.
Der Chat-Button sollte unten rechts erscheinen.
Joomla-eigenen Cache leeren: System → Cache löschen.

✓ Wenn der Button erscheint, ist die Einbindung erfolgreich. Testen Sie eine Frage aus Ihrer Wissensdatenbank.

Häufige Fragen & Probleme

Der Editor entfernt meine Script-Tags

Das ist das häufigste Problem bei Joomla. TinyMCE und andere WYSIWYG-Editoren entfernen <script>-Tags aus Sicherheitsgründen. Lösung: Klicken Sie auf „Editor deaktivieren" im Modul, oder wechseln Sie in den reinen HTML-Quelltext-Modus, bevor Sie den Code einfügen.

Chat-Button erscheint nicht

Prüfen Sie den Browser-Cache (Strg+Shift+R).
Leeren Sie den Joomla-Cache: System → Cache löschen.
Prüfen Sie in der Browser-Konsole (F12) auf JavaScript-Fehler.
Stellen Sie sicher, dass das Modul auf „Allen Seiten" zugewiesen ist.

CSP-Header blockiert das Script

Falls Ihr Hosting oder Template einen Content-Security-Policy-Header setzt, muss die Domain firstbot.de als erlaubte Script-Quelle eingetragen werden. Kontaktieren Sie dazu Ihren Hosting-Anbieter oder prüfen Sie die .htaccess-Datei.

Weitere Hilfe benötigt?
Schreiben Sie uns unter g.kunze@mukxx.de – wir helfen gern bei der Einbindung.

Tipp: Seiten-Kontext aktivieren

Nach der Einbindung: Aktiviere im Dashboard unter Trainingsdaten → „Seiten-Kontext“ die Option, damit dein Bot den Inhalt der Seite kennt, auf der dein Besucher gerade ist. So beantwortet er Fragen zu Produkten und Artikeln direkt – und lernt aus diesen Seiten dazu.