Website-Widget

Das Widget ist der Chat Ihres Bots direkt auf Ihrer Website: eine runde Schaltfläche in der Ecke der Seite, aus der sich ein Gespräch öffnet. Für Besucher ist es ein weiterer Weg, Sie zu erreichen; für den Bot ist es ein gewöhnlicher Kanal mit denselben Reaktionen und denselben Operator-Dialogen wie in den Messengern. Einen Überblick über Mehrkanalfähigkeit gibt die Seite Kanäle.

Die Installation besteht aus einem einzigen Code-Schnipsel in Ihrer Website-Vorlage. Alles Weitere wird im Dashboard konfiguriert und ohne Änderungen an der Website übernommen.

Wo Sie den Einbindungscode finden

Öffnen Sie im Dashboard den Bereich Widget → Block Auf der Website installieren → Feld Installationscode. Die Schaltfläche Kopieren legt den gesamten Schnipsel in die Zwischenablage.

Der Code sieht so aus – mit Ihrem eigenen Schlüssel anstelle der Auslassungspunkte:

<script>
  window.mybot = { key: "eu-1a2b3c4d-..." };
</script>
<script async src="https://getmybot.dev/loader.js"></script>

Steht dort statt des Codes der Hinweis, dass für diesen Bot noch kein Installationsschlüssel ausgestellt wurde, ist der Website-Widget-Kanal noch nicht mit dem Bot verbunden. Wenden Sie sich an den Support: Der Schlüssel wird beim Verbinden des Kanals ausgestellt.

Unter dem Code steht ein Hinweis, welchen Host das Widget kontaktiert. Wenn Ihre Website eine CSP (Content Security Policy) einsetzt, erlauben Sie diesem Host das Laden von Skripten und Netzwerkanfragen – sonst blockiert der Browser das Widget stillschweigend.

Wohin der Code gehört

Der Schnipsel gehört in das HTML jeder Seite, auf der das Widget erscheinen soll. In der Praxis heißt das: einmal in die gemeinsame Vorlage – Footer, das Feld „Code vor </body>" Ihres CMS oder ein Container im Tag-Manager.

Die Regeln sind kurz:

  • Der beste Platz ist direkt vor dem schließenden </body>. <head> funktioniert auch, dann verbringt der Browser aber Zeit mit dem Widget, bevor er Ihre Inhalte darstellt.
  • Die Reihenfolge der beiden Tags ist wichtig: Das erste setzt den Schlüssel, das zweite lädt das Widget. Nicht vertauschen und nicht über die Seite verteilen.
  • Das zweite Tag trägt async und blockiert damit das Rendering nicht. Behalten Sie dieses Attribut bei.
  • Ein Schnipsel pro Seite. Zwei Kopien bedeuten zwei Startversuche.

Alles Weitere erledigt der Loader: Er ermittelt, aus welchem Rechenzentrum Ihr Bot bedient wird, und lädt den Widget-Code von dort. Dafür ist von Ihnen nichts nötig.

Der Installationsschlüssel ist öffentlich

Der Schlüssel im ersten Tag ist eine öffentliche Kennung Ihres Bots, kein Passwort. Er steht im Quelltext der Seite: Jeder Besucher kann „Seitenquelltext anzeigen" öffnen und ihn lesen. Jedes Chat-Widget funktioniert so, und das ist in Ordnung.

Wichtig zu wissen:

  • Mit dem Schlüssel kann man sich nicht im Dashboard anmelden, fremde Dialoge lesen, die Abonnentenliste exportieren oder etwas am Bot ändern. Er ermöglicht genau eines: ein neues Gespräch mit diesem Bot zu beginnen.
  • Behandeln Sie den Schlüssel nicht als Geheimnis. Ihn zu verstecken oder zu verschleiern bringt nichts.
  • Muss der Schlüssel ersetzt werden (etwa nach der Trennung von einem Dienstleister), erledigt das der Support. Nach dem Austausch funktioniert der alte Code auf der Website nicht mehr und muss aktualisiert werden.

Liste erlaubter Domains

Das Widget hat eine Liste erlaubter Domains (Origin-Allowlist) – die Adressen, von denen aus das Widget arbeiten darf. Sie wird beim Verbinden des Kanals gesetzt und lässt sich später ändern, ohne den Schlüssel neu auszustellen: Ihr Code auf der Website bleibt unverändert.

Einträge sind Origins: Schema, Host und – falls nicht Standard – Port.

https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000

Der Abgleich ist exakt, Zeichen für Zeichen:

  • Es gibt keine Platzhalter. https://*.example.com funktioniert nicht – listen Sie Subdomains einzeln auf.
  • example.com und www.example.com sind verschiedene Einträge. Antwortet Ihre Seite auf beiden, brauchen Sie beide.
  • http:// und https:// sind ebenfalls verschiedene Einträge. Meist genügt https://, eine Testumgebung auf http:// muss aber ausdrücklich ergänzt werden.
  • Kein Pfad: https://example.com/shop wird abgelehnt, ein Origin ist nur die Website-Adresse.

Steht Ihre tatsächliche Domain nicht auf der Liste, startet das Widget nicht. Der Browser des Besuchers erhält die Ablehnung „origin not allowed", der Chat öffnet sich schlicht nicht. Typisch tritt das nach einem Domainwechsel, einer neuen Subdomain oder einer zweiten Sprachversion unter eigener Adresse auf – jede davon braucht einen eigenen Eintrag.

Ist die Liste leer, gibt es keine Einschränkung und das Widget funktioniert von überall. Werten Sie das als „noch nicht konfiguriert", nicht als bewusst offen gelassen: Sobald Sie Ihre Domains kennen, tragen Sie sie ein.

Was die Einschränkung leistet – und was nicht

Sie leistet: Eine fremde Website kann Ihr Widget nicht einbetten. Sonst könnte jemand Ihren Schnipsel auf seine eigene Seite kopieren, und die Browser echter Besucher würden den Inhalt der Gespräche mit Ihrem Bot an diese Seite ausliefern. Genau das verhindert die Liste.

Sie leistet nicht: Schutz vor jemandem, der den Schlüssel kopiert hat und die Plattform direkt anspricht – nicht aus dem Browser, sondern etwa per Skript. Den Header mit der Website-Adresse setzt der Browser; ein Programm außerhalb des Browsers kann ihn weglassen oder beliebig setzen. Betrachten Sie die Liste daher als Einbettungsbeschränkung, nicht als Sicherheitsgrenze. Gegen Missbrauch schützen die Ratenbegrenzung und die Dialogmoderation der Plattform, nicht diese Liste.

Erscheinungsbild

Unter Widget → Erscheinungsbild stellen Sie ein:

  • Position – die Schaltfläche unten links oder unten rechts.
  • Akzentfarbe – Farbe der Schaltfläche und der Chat-Elemente. Nehmen Sie Ihre Markenfarbe, damit das Widget nicht fremd wirkt.
  • Chat-Name – Beschriftung der Schaltfläche und Titel des Chat-Fensters. Meist Ihr Firmenname oder der Name, mit dem sich der Bot vorstellt.

Daneben gibt es eine Vorschau – ein lebendes Widget, das das Ergebnis schon vor dem Speichern zeigt.

Eine Begrüßungsnachricht gibt es im Widget noch nicht: Mehr als diese drei Einstellungen sind es nicht. Die erste Nachricht sendet der Bot als Antwort auf den Besucher, nach Ihren üblichen Reaktionen.

Änderungen erreichen Ihre Website von selbst: Das Widget liest seine Einstellungen beim Laden der Seite, der eingefügte Code muss nie angepasst werden.

Besucher sind anonym

Ein Besucher füllt nichts aus, um zu schreiben. Beim ersten Start erhält das Widget von der Plattform eine anonyme Besucherkennung und speichert sie im Browser, damit jemand bei der Rückkehr sein bisheriges Gespräch sieht und keinen leeren Chat.

Daraus folgt:

  • In den Dialogen erscheint ein solcher Besucher als anonym: kein Name, keine Telefonnummer, keine E-Mail, solange er sie nicht selbst schreibt.
  • Die Kennung lebt in genau einem Browser. Ein anderer Browser, ein anderes Gerät oder gelöschte Website-Daten bedeuten einen neuen Besucher mit leerem Verlauf.
  • Ein anonymer Besucher kann mit einem Kunden verknüpft werden, den Sie bereits kennen – etwa einem angemeldeten Nutzer Ihres Kundenbereichs. Wie das geht, steht im nächsten Abschnitt.

Einen Besucher mit Ihrem eigenen Nutzer verknüpfen

Ist ein Besucher auf Ihrer Website bereits angemeldet, können Sie der Plattform mitteilen, wer er ist. Nach der Verknüpfung ist das Gespräch nicht mehr anonym: Es wird mit dem Profil dieser Person zusammengeführt, und ihre früheren anonymen Nachrichten gehen nicht verloren.

Dafür genügt ein Aufruf mit einer Funktion, die den Nachweis liefert:

mybot.identify(async (visitorId) => {
  const res = await fetch("/mybot-sign", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userId: currentUser.id, visitorId }),
  });
  return res.json(); // { userId, signature, expiresAt }
});

Das Widget ruft Ihre Funktion mit visitorId auf – der aktuellen anonymen Besucher-ID für diesen Browser, dem einzigen Wert, den nur das Widget kennt – und wartet, bis sie { userId, signature, expiresAt } zurückgibt oder auflöst. Die einzige Aufgabe Ihrer Funktion ist es, visitorId an Ihren eigenen Server weiterzugeben, zusammen mit der ID des angemeldeten Nutzers (currentUser.id oben steht für das, was das auf Ihrer Seite ist), und genau das zurückzugeben, was Ihr Server antwortet. Die eigentliche Signierung findet auf Ihrem Server statt, nicht in dieser Funktion – siehe unten.

Ein Callback, kein fertiger Wert und kein direkter Zugriff auf visitorId, aus zwei Gründen:

  • Timing. Das Widget erzeugt visitorId asynchron beim Start – der Wert existiert nicht in dem Moment, in dem das Loader-Skript läuft, und mybot.identify selbst wird erst installiert, nachdem das abgeschlossen ist (mehr dazu weiter unten). Sobald Ihre Seite mybot.identify überhaupt aufrufen kann, ist die ID, die Ihre Funktion erhält, deshalb garantiert echt. Ein einfacher Getter hätte diese Garantie nicht: Nichts würde eine Seite daran hindern, ihn eine Zeile zu früh zu lesen und nichts zurückzubekommen – und stillschweigend eine Signatur zu erzeugen, die nie verifiziert, ohne jeden Hinweis warum.
  • Umfang. Ihr eigener Seitencode muss visitorId nie selbst halten, speichern oder herumreichen – er existiert nur innerhalb dieser einen Funktion, für den einen Aufruf, den sie braucht.

visitorId ist ab dem Moment, in dem sie das Widget verlässt, eine übertragbare Berechtigung (bearer capability): Wer für sie eine Signatur bekommt, kann mit der Sitzung dieses Besuchers zusammengeführt werden. Senden Sie sie nur an Ihren eigenen Server, über Ihre eigene authentifizierte Anfrage, und sonst nirgendwohin – loggen Sie sie nicht, geben Sie sie nicht an Dritte weiter und packen Sie sie nicht in einen clientseitigen Analytics-Aufruf.

Die Signatur wird ausschließlich auf Ihrem eigenen Server berechnet

Innerhalb Ihrer Funktion oben berechnet Ihr eigener Server – niemals der Browser – die Signatur: ein HMAC-SHA256, mit dem Widget-Secret als Schlüssel, hexadezimal, die ersten 32 Zeichen, über drei zu einer Nachricht zusammengefügte Werte. Dieselbe Formel steht im Dashboard neben dem Secret unter „Signing algorithm":

signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)

Jedes + "\n" + oben steht für ein echtes Zeilenumbruchzeichen zwischen den Teilen, nicht für die zwei Zeichen Backslash und n. Nimmt Ihre HMAC-Funktion die Nachricht als eine Zeichenkette entgegen, fügen Sie die drei Teile mit einem echten Zeilenumbruch zusammen – drei separate .update()-Aufrufe ohne Zeilenumbruch dazwischen hashen eine andere, falsche Nachricht.

Die drei Teile:

  • userId – die ID des angemeldeten Nutzers, derselbe Wert, den Ihr Server von der Funktion oben erhält und in seiner Antwort zurückgibt.
  • visitorId – die anonyme Besucher-ID, die Ihre Funktion als Argument erhalten und unverändert an Ihren Server weitergegeben hat.
  • expiresAt – ein Unix-Zeitstempel in Sekunden (nicht Millisekunden), bis zu dem genau diese Signatur gültig bleibt, ausgestellt von Ihrem Server beim Signieren. Die Plattform lehnt einen Aufruf ab, dessen expiresAt bereits in der Vergangenheit liegt, ebenso einen, der mehr als 24 Stunden in der Zukunft liegt – signieren Sie also unmittelbar bevor Sie den Wert aus Ihrer Funktion zurückgeben, nicht einmalig zum Zwischenspeichern für spätere Anfragen.

Diese Ablauffrist ist der eigentliche Kern der Änderung, kein Nebendetail. Die vorherige Formel deckte nur die Nutzer-ID ab, weshalb eine einmal erfasste Signatur – irgendwo geloggt, aus dem Datenverkehr abgegriffen, wie auch immer – für immer gültig blieb und zu jedem Besucher passte, nicht nur zu dem, für den sie ausgestellt wurde. Wer eine solche Signatur in die Hände bekam, konnte sie in einem völlig anderen Browser abspielen, und die Plattform hätte das anonyme Surfverhalten eines Fremden mit dem Profil eines echten Kunden zusammengeführt. Die Bindung der Signatur an eine bestimmte visitorId und eine kurze Lebensdauer schließen beide Enden dieser Lücke: Sie gilt nur für die Sitzung, für die sie ausgestellt wurde, und für keine andere, und sie hört ganz auf zu gelten, sobald expiresAt verstrichen ist – selbst eine durchgesickerte Signatur bleibt so nur eine kurzlebige Gefahr für eine einzelne Sitzung, keine dauerhafte.

Berechnen Sie alle drei Werte auf Ihrem Server und geben Sie sie aus Ihrer Funktion fertig zurück. Das ist keine Formsache: Um die Signatur im Browser zu berechnen, müssten Sie das Secret dorthin ausliefern – also jedem Besucher der Seite aushändigen. Danach könnte sich jeder als beliebiger Kunde von Ihnen ausgeben und dessen Gespräch mitlesen. Die Signatur (und visitorId/expiresAt, für die sie berechnet wurde) darf zurück an den Browser, das Secret nicht.

Der Aufruf selbst zeigt nichts auf dem Bildschirm: Die Verknüpfung geschieht serverseitig und still. Wirft Ihre Funktion einen Fehler oder wird ihr Promise abgelehnt, oder lehnt die Plattform die resultierende Signatur ab – Nichtübereinstimmung, oder expiresAt fehlt, liegt schon in der Vergangenheit oder mehr als 24 Stunden voraus –, passiert darüber hinaus nichts: Der Besucher merkt nichts und schreibt weiter als Anonymer.

mybot.identify existiert nicht sofort – es erscheint, sobald das Haupt-Bundle des Widgets geladen ist, zusammen mit einer echten visitorId (siehe „Timing" oben). Rufen Sie es aus einem Load-Handler der Seite auf, nicht als erste Zeile im <head>.

Wo Sie das Secret finden und wie Sie es wechseln

Das Widget-Secret ist der Schlüssel, mit dem Sie signieren. Es liegt in den Widget-Einstellungen im Abschnitt „identify() secret". Steht dort, das Widget sei noch nicht verbunden, verbinden Sie zuerst den Web-Kanal – das Secret erscheint zusammen mit ihm.

Anzeigen. Die Schaltfläche „Reveal secret" holt den Wert. Er erscheint nicht im Klartext: Zuerst sehen Sie Punkte, und ein eigener Umschalter „Show" zeigt die Zeichen („Mask" verbirgt sie wieder). Daneben liegt „Clear from screen", das den Wert aus der Ansicht entfernt.

Anzeigen können Sie beliebig oft, und das Anzeigen macht nichts ungültig: Das Secret bleibt auch nach dem Schließen des Bildschirms gültig. Grund dafür ist, dass es verschlüsselt und nicht gehasht gespeichert wird – die Plattform braucht den echten Wert, um jede Signatur zu prüfen. Wenn Sie in einem halben Jahr ein neues Backend ausrollen, schauen Sie einfach wieder nach.

Nach dem Kopieren räumen Sie selbst auf. Die Zwischenablage kann die Plattform nicht leeren: Aus dem Browser heraus geht das nicht zuverlässig, deshalb versprechen wir es auch nicht. Entfernen Sie den Wert vom Bildschirm und leeren Sie die Zwischenablage von Hand, besonders an einem gemeinsam genutzten Rechner.

Wechseln. Die Schaltfläche „Rotate secret", mit Bestätigungsschritt. Das ist sofort brechend: In dem Moment, in dem das neue Secret existiert, prüft das alte nicht mehr. Es gibt kein Überlappungsfenster – keinen Augenblick, in dem beide Schlüssel gelten.

Was bricht, ist genau die Verknüpfung von Besuchern mit Ihren Nutzern. Die Gespräche werden nicht unterbrochen – Besucher schreiben weiter und bekommen Antworten, nur eben anonym – bis Ihr Backend mit dem neuen Secret signiert. Einbindungscode und Liste erlaubter Domains bleiben unberührt, an Ihrer Website ist nichts zu ändern.

Wechseln Sie deshalb bewusst: Bereiten Sie zuerst das Backend-Deployment mit dem neuen Wert vor und drücken Sie erst dann „Rotate secret". Es zu drücken, um zu sehen, was passiert, ist eine schlechte Idee. Der neue Wert wird direkt nach dem Wechsel auf dem Bildschirm angezeigt, Sie können ihn also sofort kopieren.

Wie sich das Widget auf der Seite verhält

Das Widget ist bewusst so gebaut, dass es Ihrer Website nicht in die Quere kommt:

  • Es lebt in einem isolierten Container (geschlossenes Shadow DOM). Ihre Styles dringen nicht hinein, die Styles des Widgets nicht hinaus. Nebeneffekt: Sie können das Widget nicht per eigenem CSS umgestalten – nutzen Sie dafür die Einstellungen zum Erscheinungsbild.
  • Der Container überspannt den Bildschirm, fängt aber keine Klicks ab: Sie gehen durch zur Seite, nur die Schaltfläche und das Chat-Fenster reagieren.
  • Das Widget liegt immer über Ihren Inhalten; eigene Ebenen können es nicht verdecken.
  • Jeder Fehler im Widget bleibt darin: Schlimmstenfalls funktioniert die Chat-Schaltfläche nicht, Ihre Website läuft weiter. Erscheint das Widget nicht, schauen Sie in die Browser-Konsole – meist ist es die CSP oder eine fehlende Domain in der Liste.

Wenn das Widget nicht erscheint

Gehen Sie der Reihe nach vor:

  1. Öffnen Sie den Seitenquelltext und prüfen Sie, ob beide Tags vorhanden sind und der Schlüssel nicht leer ist.
  2. Prüfen Sie, ob die Website-Adresse exakt der Liste entspricht, samt https:// und www.
  3. Sehen Sie in die Browser-Konsole: Eine Meldung zur Content Security Policy bedeutet, dass der Host der Plattform in Ihrer CSP erlaubt werden muss.
  4. Stellen Sie sicher, dass kein Werbeblocker das Widget entfernt – testen Sie in einem privaten Fenster ohne Erweiterungen.

Wie geht es weiter