Chatbot in eine Webseite einbinden

Diese Seite richtet sich an Entwickler und beschreibt die technische Einbindung des Chatbots in eine eigene Webseite über das Skript chatbot.js. Sie finden alle hier beschriebenen Werte und Code-Schnipsel auch in der App in der Detailansicht des Chatbots unter Einbinden.

Das Einbettungs-Skript

Um den Chatbot zu integrieren, binden Sie ein einzelnes <script>-Tag in den HTML-Code Ihrer Webseite ein. Danach erscheint der Chatbot als rundes Symbol in der unteren rechten Ecke des Bildschirms.

<script src="https://<ihre-skai-instanz>/chatbot.js" data-token="eyJhbGciOiJIUzI1N..." async></script>

Das Skript erzeugt eine schwebende Schaltfläche und lädt die Chat-Oberfläche in einem <iframe>. Es liest folgende Attribute:

data-token (erforderlich) – Identifiziert den Chatbot. Das Token wird automatisch erzeugt und auf der Seite Einbinden des jeweiligen Chatbots angezeigt. Es ist fest an diesen einen Chatbot gebunden.
data-client (optional) – Ein signiertes Token mit Anmeldedaten, Kontext und Tools für angemeldete Besucher (siehe Anmeldedaten und Kontext übergeben).
async – Empfohlen, damit das Skript das Laden Ihrer Seite nicht blockiert.

Aussehen und Position anpassen

Optional können Sie Aussehen und Position über CSS-Custom-Properties am :root-Element überschreiben. Das folgende Beispiel zeigt alle verfügbaren Eigenschaften mit ihren Standardwerten:

<style>
  :root {
    --skai-chatbot-offset-bottom: 0px;
    --skai-chatbot-offset-right: 0px;
    --skai-chatbot-window-offset-bottom: 0px;
    --skai-chatbot-window-offset-right: 0px;
    --skai-chatbot-toggle-scale: 1.0;
    --skai-chatbot-toggle-border-radius: 9999px;
    --skai-chatbot-toggle-height: 56px;
    --skai-chatbot-toggle-width: 56px;
    --skai-chatbot-toggle-padding: 12px;
    --skai-chatbot-z-index: 50;
  }
</style>

Eigenschaft	Bedeutung
`--skai-chatbot-offset-bottom`/`--skai-chatbot-offset-right`	Abstand der Schaltfläche (und des Fensters) vom unteren bzw. rechten Bildschirmrand.
`--skai-chatbot-window-offset-bottom`/`--skai-chatbot-window-offset-right`	Zusätzlicher Abstand nur für das geöffnete Chat-Fenster.
`--skai-chatbot-toggle-scale`	Skalierungsfaktor der Schaltfläche.
`--skai-chatbot-toggle-border-radius`	Eckenradius der Schaltfläche (Standard: rund).
`--skai-chatbot-toggle-height`/`--skai-chatbot-toggle-width`	Höhe und Breite der Schaltfläche.
`--skai-chatbot-toggle-padding`	Innenabstand der Schaltfläche.
`--skai-chatbot-z-index`	Stapelreihenfolge (z-index) von Schaltfläche und Fenster.

Anmeldedaten und Kontext übergeben

Für angemeldete Besucher können Sie dem Chatbot zusätzliche Informationen mitgeben: Name und E-Mail des Nutzers, freien Kontext für die KI sowie Tools, über die der Chatbot anwendungsspezifische Daten abrufen kann.

Diese Daten werden als JWT (JSON Web Token) mit folgender Payload-Struktur (TypeScript) kodiert. Aktuell sind nur Eigenschaften der Typen string, array, integer und boolean erlaubt:

type ClientData = {
  user?: {
    name: string,
    email: string,
  },
  context?: string[],
  tools?: [
    {
      name: string,
      title: string,
      description: string,
      inputSchema?: {
        type: "object",
        properties?: {
          [name in string]: {
            type: "string"|"array"|"integer"|"boolean",
            description: string,
          }
        },
        required?: string[]
      }
    }
  ]
}

Beispielkonfiguration:

{ user: { name: "John Doe", email: "[email protected]" }, context: [ "The user has an account balance of 42$.", "The user lives at 17 Main Street." ], tools: [ { name: "recent-purchases", title: "Recent Purchases", description: "Lists the recent purchases of the user", inputSchema: { type: "object", properties: { status: { type: "string", description: "One of ['ORDERED', 'PROCESSED', 'SHIPPED', 'RECEIVED']" } }, required: ["status"] } } ] }

Die Signierung erfolgt mit dem HMAC-Algorithmus. Das benötigte Geheimnis finden Sie auf der Seite Einbinden des Chatbots.

Das erzeugte Token übergeben Sie anschließend über das Attribut data-client:

<script src="..." data-token="..." data-client="eyJhbGciOiJIUzI1N..." async></script>

Ändert sich das data-client-Attribut zur Laufzeit (z. B. beim An- oder Abmelden eines Nutzers), übernimmt der Chatbot die neuen Daten automatisch – ein Neuladen der Seite ist nicht erforderlich.

Tools bereitstellen

Über das Feld tools in den Client-Daten stellen Sie dem Chatbot Funktionen Ihrer Anwendung zur Verfügung. Möchte der Chatbot ein solches Tool ausführen, ruft er einen Callback auf, den Sie am window-Objekt hinterlegen:

window.skaiChatbot.toolCallback = async function(request) {
  // request serverseitig prüfen und signierte JWT-Antwort zurückgeben
}

Aus Sicherheitsgründen muss die Validierung des übergebenen JWT nicht im Browser, sondern auf einer sicheren Serverseite erfolgen. Validierung und Signierung erfolgen mit dem RSA256-Algorithmus. Die Antwort des Callbacks muss ebenfalls ein signiertes JWT sein. Beispiel für die serverseitige Implementierung in JavaScript:

// Server-Side
function(request) {
  const jwt = require('jsonwebtoken');
  const payload = jwt.verify(request, publicKey, { algorithms: ["RS256"] });
  const toolName = payload.toolName
  const executionId = payload.executionId
  const parameters = payload.parameters // type { [key in string]: string }

  let toolResult = ''
  switch (toolName) {
     case "your-tool-name":
        // ... compute result
        toolResult = "your-tool-result"
        break
     default:
        toolResult = "Unknown tool " + toolName
  }

  const resultPayload = { executionId: executionId, result: toolResult }
  const resultToken = jwt.sign(resultPayload, privateKey, { algorithm: "RS256" })
  return resultToken
}

Die dafür benötigten Schlüssel erzeugen Sie auf der Seite Einbinden über die Schaltfläche Generieren. Es entstehen zwei Schlüssel:

Öffentlicher Schlüssel – zur Validierung der Tool-Aufrufe des Chatbots (entspricht publicKey im Beispiel).
Privater Schlüssel – zur Signierung Ihrer Tool-Antworten (entspricht privateKey im Beispiel).

15 June 2026