Zum Inhalt

Widget (JWT) einbetten

Das Clye-Widget kann extern in eine Website oder ein Portal eingebettet werden. Dafür gibt es zwei gängige Varianten:

  • JWT-Widget: Du erzeugst ein signiertes JWT mit einem bot-spezifischen Secret und übergibst es direkt in der URL.
  • Assistant Access Link (opaque Token): Du erzeugst serverseitig einen kurzen Token; die Claims werden im AI HUB gespeichert und bei jeder Nutzung enforced.

Beide Varianten nutzen dieselbe Widget-Route GET /widget/{token} – je nach Token-Format ist das Verhalten aber unterschiedlich.

Schnellstart: iFrame-Einbettung

Du bindest das Widget als iFrame ein:

<iframe
  src="https://dein-hub.example/widget/<TOKEN>"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write"
></iframe>

Wichtig:

  • Token niemals im Browser des Endnutzers generieren (Secret bleibt serverseitig).
  • Token kurzlebig halten und pro Nutzer/Session neu erzeugen.

Variante A: JWT-Widget

Was ist das?

Beim JWT-Widget ist <TOKEN> ein echtes JWT (es enthält Punkte, z. B. header.payload.signature). Das Widget:

  1. liest aus dem Token den botId,
  2. lädt den Bot (inkl. widgetJwtSecret) aus der Datenbank,
  3. verifiziert die Signatur mit dem Secret des Bots,
  4. rendert das Chat-Widget für genau diesen Bot.

Welche Claims sind erforderlich?

Minimal benötigst du:

  • botId (number): ID des Bots/Assistenten
  • exp (number): Ablaufzeitpunkt als Unix-Timestamp (Sekunden)

Optional unterstützt das Widget zusätzlich:

  • loginUrl (string): Wenn das Token abgelaufen/ungültig ist, wird im Fehlerzustand ein „Neu anmelden“-Link zu dieser URL angezeigt.

JWT serverseitig erzeugen (Beispiel)

Node.js (mit jsonwebtoken):

import jwt from "jsonwebtoken";

const secret = process.env.CLYE_WIDGET_SECRET!; // aus Bot-Settings
const botId = 123;

const token = jwt.sign(
  {
    botId,
    loginUrl: "https://portal.example/sign-in", // optional
  },
  secret,
  {
    expiresIn: "15m",
  },
);

Dann nutzt du https://dein-hub.example/widget/${token} als iFrame-Quelle.

Typische Fehlerbilder

  • TokenExpiredError: Das Token ist abgelaufen → neues JWT erzeugen.
  • JsonWebTokenError: Signatur/Format ist ungültig → Secret prüfen (richtiges Bot-Secret?) und Payload/Clock-Skew prüfen.
  • Bot nicht gefunden / Secret nicht konfiguriert: Bot-ID falsch oder Widget-Secret ist für den Bot nicht gesetzt.

Was ist das?

Beim Assistant Access Link ist <TOKEN> kein JWT, sondern ein kurzer opaque Token (ohne Punkte). Der AI HUB speichert dazu serverseitig einen JWT-Payload (Claims) in der Datenbank. Das hat zwei Vorteile:

  • Kein URL-Size-Limit: Du kannst umfangreichere Claims/Filter/Features hinterlegen, ohne sie in die URL zu packen.
  • Enforcement: Tool-Policies, Feature-Toggles (z. B. Chat-Historie) und Filter werden serverseitig geprüft.

Ablauf

  1. Dein Server ruft POST /api/assistant-link auf.
  2. Die Antwort enthält token, url (/widget/{token}) und jwtPayload.
  3. Du bettest die url in einen iFrame ein oder leitest dorthin weiter.

Details und Beispiele findest du hier: /docs/assistant-access-links

Welche Variante soll ich nehmen?

  • JWT-Widget ist gut, wenn du nur wenige Claims brauchst (z. B. botId, exp) und die Logik sehr einfach bleibt.
  • Assistant Access Link ist die bessere Wahl, wenn du:
  • Features/Policies serverseitig enforced brauchst,
  • Filter/Permission-DSL nutzen willst,
  • den Zugriff sauber zeitlich/inhaltlich begrenzen möchtest,
  • oder wenn du vermeiden willst, dass Claims direkt in der URL stehen.