TaskMonkey Handbuch

Widget einbetten

Ein Script-Tag auf der Kundenseite, und das Chat-Widget ist da.

Das Widget wird per einzelnem Script-Tag eingebunden. Kein npm-Package, kein Build-Schritt — der Tag rendert das Widget unmittelbar hinter sich in einem Shadow-DOM-Container.

Inline-Chat (chat.js)

Der Chat erscheint direkt an der Stelle des Script-Tags. Gut für dedizierte Chat-Seiten oder als Block in einem Layout.

<script src="https://taskmonkey.example.com/chat.js"
        data-tenant="mein-workspace"></script>

Die ausgelieferte URL (https://taskmonkey.example.com/chat.js) variiert je nach Betreiber — dein Betreiber sagt dir die richtige Basis-URL.

Bubble-Chat (chat-icon.js)

Ein kleiner Chat-Button unten rechts auf der Seite. Klick öffnet den Chat als Bubble.

<script src="https://taskmonkey.example.com/chat-icon.js"
        data-tenant="mein-workspace"></script>

Typisch ins Footer-Template der Website, damit er auf allen Seiten erscheint.

Script-Tag-Attribute

Beide Skripte verstehen dieselben Attribute:

Attribut Pflicht Bedeutung
data-tenant ja Workspace-Code (bestimmt, welche public.php greift)
data-chat-id nein Feste chat_id — gut für serverseitig geschaltete Sessions
data-api-url nein Override des API-Endpunkts, default /chat
data-fullscreen nein Widget füllt den verfügbaren Raum komplett (nur chat.js)
data-no-autofocus nein Input-Feld nicht automatisch fokussieren (nur chat.js)

Beispiel: Vollbild-Chat auf eigener Seite

<!DOCTYPE html>
<html>
<head><title>Support</title></head>
<body style="margin:0; height:100vh;">
    <script src="https://taskmonkey.example.com/chat.js"
            data-tenant="mein-workspace"
            data-fullscreen></script>
</body>
</html>

Beispiel: Mehrere Widgets mit unterschiedlicher Identität

Wenn dein Workspace mehrere öffentliche Chat-Varianten anbietet (z. B. einmal FAQ-Assistent, einmal Produkt-Berater), kannst du die chat_id explizit setzen und serverseitig die passende Rolle zuordnen:

<!-- Produktseite -->
<script src="https://taskmonkey.example.com/chat-icon.js"
        data-tenant="mein-workspace"
        data-chat-id="product-advisor"></script>

<!-- FAQ-Seite -->
<script src="https://taskmonkey.example.com/chat-icon.js"
        data-tenant="mein-workspace"
        data-chat-id="faq-bot"></script>

(Wie die chat_id auf eine konkrete Rolle gemappt wird, ist optional und geht auf Betreiber-Ebene zu konfigurieren — frag nach, wenn du das brauchst.)

Chat-ID und Persistenz

Ohne data-chat-id erzeugt das Widget einmalig eine UUID und speichert sie in localStorage:

  • Gleicher Browser, andere Seite: selbe chat_id → Verlauf bleibt
  • Gleicher Besucher, anderer Browser: neue chat_id → neuer Chat
  • Private/Incognito-Modus: jede Session neu

Wenn du den Verlauf zurücksetzen willst (z. B. nach Abmeldung), gibt es zwei Wege:

  1. Benutzer klickt den Reset-Button im Widget (falls gerendert)
  2. Eigene Logik: localStorage.removeItem('chat_id') und Seite neu laden

CORS & Cross-Domain

Das Widget läuft typisch auf einer anderen Domain als die TaskMonkey-Plattform. Der Server ist dafür konfiguriert — du musst nichts tun, solange du die vom Betreiber angegebene Basis-URL verwendest.

Sicherheit: HTTPS und Content Security Policy

  • HTTPS: erforderlich für QR-Scanner und Voice-Input (Browser-Richtlinie)
  • CSP: wenn deine Kundenseite eine strikte Content Security Policy hat, muss sie script-src und connect-src für die TaskMonkey-Domain freigeben:
Content-Security-Policy:
    script-src 'self' https://taskmonkey.example.com;
    connect-src 'self' https://taskmonkey.example.com;
    img-src 'self' data: blob: https://taskmonkey.example.com;

Platzierung-Empfehlungen

Inline-Chat:

  • Ein <div>-Wrapper um den Script-Tag, wenn du die Größe begrenzen willst: 
    <div style="max-width: 600px; height: 500px;">
    <script src=".../chat.js" data-tenant="..."></script>
</div>
  • Nicht in versteckte/gecachte Template-Teile einfügen (z. B. unter display:none) — der Inhalt wird trotzdem geladen, aber nicht interaktiv.

Bubble-Chat:

  • Idealer Ort: direkt vor </body>
  • Nur einmal pro Seite einbinden
  • Wenn du ihn auf bestimmten Seiten nicht willst, dort weglassen

Testen im lokalen Browser

Während der Entwicklung:

tm chat --public

Für einen echten Browser-Test ohne Kundenseite: der Betreiber hat typisch eine Test-Seite (z. B. https://taskmonkey.example.com/chat/flutter-test oder eine Demo-Page). Frag danach.

Debug

  • Widget erscheint nicht: Browser-Konsole öffnen. CORS-Fehler? 404? Falsche data-tenant?
  • Widget lädt, aber bleibt weiß: public.php existiert nicht oder hat einen Syntaxfehler → tm sync und Output prüfen
  • Chat antwortet nicht: tm monitor öffnen, Nachricht senden, schauen was passiert. Wenn gar nichts auftaucht: Request kommt nicht durch (CORS, HTTPS, API-URL falsch)
Zuletzt aktualisiert: 2026-04-19