Zum Hauptinhalt springen

Widget (JWT) einbetten

Das Clye-Widget kann extern in eine Website oder ein Portal eingebettet werden. Dafür gibt es zwei gängige Varianten. Die vollständige API Referenz findest du unter clye.ai/api.

  • 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 CLYE AI gespeichert und bei jeder Nutzung enforced.

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

Wenn du nicht nur das iFrame-Widget nutzen willst, sondern auch das öffentliche Script-Widget oder ein eigenes Frontend mit AI SDK bauen möchtest, siehe zusätzlich:

Schnellstart: iFrame-Einbettung​

Du bindest das Widget als iFrame ein:

<iframe
  src="https://clye.ai/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://clye.ai/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 CLYE AI 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.

Mobile Darstellung und Dokumentzugriff​

Das eingebettete Widget wurde in den letzten Produktständen besonders für mobile Nutzung stabilisiert. Achte bei eigenen Einbettungen vor allem auf diese Punkte:

  • nutze eine ausreichend breite und hohe iFrame-Fläche, damit Header, Eingabebereich und Dateivorschauen nicht abgeschnitten werden
  • teste Download-Links und Datei-Vorschauen auch auf Smartphones und Tablets
  • wenn du den Dokumentzugriff bewusst einschränken willst, prüfe zusätzlich die Einstellungen des Bots für sichtbare Dokumente und Download-Verhalten

Wenn du statt eines statischen JWT lieber einen kontrollierten, serverseitig erzeugten Zugang mit klarer Rücksprung-Logik brauchst, ist meist der Assistant Access Link die bessere Wahl.

Downloads im eingebetteten Widget​

Wenn du Dokumente über ein eingebettetes Widget bereitstellst, können Downloads heute auch für externe Nutzer ohne klassische Anmeldung funktionieren – vorausgesetzt, der Zugriff wird über den Widget-Token oder Access-Link sauber freigegeben. Das ist besonders nützlich für Support-, Service- oder Produktdokumente in öffentlichen oder portalgebundenen Widgets.

Wichtig für die Einbettung: Im Widget werden aktuell keine Quellen-Chips angezeigt. Datei-, Bild- und Download-Links im Widget zeigen auf die konfigurierte Widget-Domain – nicht auf die Domain der Seite, in die du das Widget eingebettet hast. Wenn du eine eigene Bot-Domain nutzt, setze deshalb die domain des Widgets passend auf diese Domain. Vom Agenten erzeugte Links bleiben dabei nutzbar.

Inhalt