Kookeebeta
Zurück zum Blog

KI-Assistent für jede Website mit einer Zeile Code

Help CenterDenis Povarov

Bisher hatte das Chat-Widget von Kookee eine Voraussetzung, um die niemand gebeten hatte: React.

Hattest du React schon, war das kein Problem. Läuft deine Marketing-Website aber auf WordPress, dein Shop auf Shopify, deine Doku auf einem Static-Site-Generator oder deine App auf Vue oder Angular, war es ein Ausschlusskriterium. Das Widget beantwortete Fragen aus deinen Hilfeartikeln, und um es zu nutzen, musstest du das richtige Framework haben.

Diese Voraussetzung fällt weg. Das Chat-Widget gibt es jetzt als einfaches Script-Tag.

Eine Zeile

HTML 
<script async src="https://kookee.dev/chat/latest.js" data-api-key="YOUR_API_KEY"></script>

Füge das vor </body> ein, und du hast einen schwebenden Assistenten, der aus den veröffentlichten Artikeln deines Hilfecenters antwortet. Kein npm install, kein Build-Schritt, keine Bundler-Konfiguration, kein Framework.

Zwei Dinge müssen stimmen, damit es funktioniert:

  1. Das echte Snippet, mit deinem API-Schlüssel schon drin, findest du im Dashboard auf der Seite Website-Widget deines Projekts. Kopiere es von dort, statt die URL abzutippen.

  2. Trag die Domain deiner Website im Projekt unter Erlaubte Origins ein. Sobald die Liste einen Eintrag hat, werden Anfragen von überall sonst abgelehnt. Genau das verhindert, dass jemand deinen Schlüssel aus dem Seitenquelltext kopiert und deinen Assistenten auf seiner eigenen Website betreibt.

Eine fehlende Domain in dieser Liste ist der häufigste Grund, warum die Chat-Blase erscheint, aber jede Frage scheitert. Kommen nie Antworten an, prüf zuerst die Origin-Liste.

Was das Widget beantwortet

Das Widget stützt sich auf deine veröffentlichten Hilfeartikel. Es durchsucht sie semantisch und nach Stichwörtern, antwortet in natürlicher Sprache und nennt die Artikel, die es genutzt hat, damit der Leser die Quelle öffnen kann.

Das ist wichtiger, als es klingt. Ein Assistent, der aus deiner Dokumentation antwortet, ist an deine Dokumentation gebunden: Er sagt Nutzern, was du tatsächlich geschrieben hast. Und wenn er etwas nicht beantworten kann, erfährst du von einer konkreten Lücke, statt zuzusehen, wie ein Allzweckmodell eine Funktion erfindet, die es bei dir gar nicht gibt.

Das Widget anpassen

Alles Visuelle steckt in data-Attributen. So passt auch jemand ohne Entwicklerkenntnisse das Widget an, indem er eine Zeile im Seiten-Template ändert:

HTML 
<script
  async
  src="https://kookee.dev/chat/latest.js"
  data-api-key="YOUR_API_KEY"
  data-title="Support"
  data-greeting="Hallo! Frag mich alles zum Produkt."
  data-placeholder="Schreib deine Frage…"
  data-launcher-label="Brauchst du Hilfe?"
  data-position="bottom-left"
  data-theme="auto"
  data-primary-color="#ff6b00"
></script>

data-position erwartet bottom-right oder bottom-left, data-theme erwartet light, dark oder auto, und data-locale legt die Sprache fest. Mit data-base-url richtest du das Widget auf einen anderen API-Host.

Das Widget rendert in einem Shadow Root. Deshalb kannst du es gefahrlos in eine Website einfügen, die du nicht selbst gebaut hast. Das CSS deiner Seite dringt nicht ein und gestaltet den Chat nicht um, und das CSS des Chats dringt nicht nach außen und zerschießt dein Layout nicht. Ein Shopify-Theme mit aggressiven globalen Selektoren lässt es in Ruhe.

Die JS-API, wenn Attribute nicht mehr reichen

Attribute decken den Normalfall ab. Soll der Assistent in deine eigene Oberfläche eingebunden werden, gibt es window.KookeeChat:

JavaScript 
KookeeChat.open();
KookeeChat.close();
KookeeChat.toggle();
KookeeChat.sendMessage('Wie setze ich mein Passwort zurück?');
KookeeChat.clearMessages();

So öffnet dein vorhandener Link „Support kontaktieren“ den Assistenten statt eines Mailprogramms:

JavaScript 
document.querySelector('#support-link').addEventListener('click', (event) => {
  event.preventDefault();
  KookeeChat.open();
});

Events sind Abonnements, und jedes gibt eine eigene Funktion zurück, mit der du es wieder kündigst:

JavaScript 
const unsubscribe = KookeeChat.on('sourceClick', (source) => {
  analytics.track('help_article_opened', { slug: source.slug });
});

on() kennt außerdem die Events open und close. Willst du die Konfiguration komplett selbst steuern statt über Attribute, ruf init() direkt auf. Es akzeptiert alles, was die Attribute können, und dazu ein paar Dinge, die sich als Attribut nicht ausdrücken lassen:

JavaScript 
KookeeChat.init({
  apiKey: 'YOUR_API_KEY',
  greeting: 'Wobei kann ich dir helfen?',
  suggestions: ['Wie fange ich an?', 'Welche Preispläne gibt es?', 'Wie kündige ich?'],
  hideLauncher: true,
  zIndex: 9999,
  offset: { x: 24, y: 96 },
  onSourceClick: (source) => window.open(`/help/${source.slug}`, '_blank'),
  onOpenChange: (isOpen) => console.log('chat open:', isOpen),
});

suggestions lohnt sich. Startfragen entscheiden, ob ein Nutzer etwas eintippt oder auf ein leeres Eingabefeld starrt und beschließt, dir doch lieber eine E-Mail zu schreiben. hideLauncher blendet die Standard-Blase aus, damit du das Widget über deinen eigenen Button öffnest, und destroy() baut alles wieder ab. Das hilft in einer Single-Page-App, wenn sich der Nutzer in einen Bereich einloggt, in den der Assistent nicht gehört.

TypeScript-Nutzer finden die Typen unter https://kookee.dev/chat/latest.d.ts.

Details, die im echten Einsatz auffallen

Die Unterhaltung übersteht die Navigation innerhalb des Tabs. Wer auf deiner Preisseite eine Frage stellt und dann zu den Funktionen weiterklickt, verliert den Faden nicht. Auch beim Minimieren bleibt die Unterhaltung erhalten, nur der Button Neuer Chat löscht sie. Für längere Antworten gibt es einen erweiterten Modus in voller Höhe, und die Beschriftung neben der Chat-Blase können Nutzer wegklicken, wenn sie lieber nur die Blase sehen.

Nichts davon ist eine Einstellung, über die du nachdenken musst. Es sind die Gründe, warum sich das Widget nicht wie ein angeflanschter iframe anfühlt.

Wenn du schon React nutzt

Für dich ändert sich nichts:

tsx 
import { KookeeChatWidget } from '@kookee/react/chat';

In einer React-App ist diese Komponente weiterhin die richtige Wahl: Sie lebt in deinem Komponentenbaum und nimmt Props wie jede andere Komponente. Das Script-Tag ersetzt sie nicht. Es ist die Antwort für die viel größere Gruppe von Websites, die nie ein React-Paket installiert hätten, nur um eine Chat-Blase zu bekommen, und das jetzt auch nicht müssen.