Chat einbetten und eigene Widgets

Es gibt im CLYE AI mehrere Wege, einen Chat außerhalb der normalen Oberfläche zu nutzen. Welcher Weg sinnvoll ist, hängt davon ab, wie viel Kontrolle du über Design, Zugriff und Verhalten brauchst.

Überblick

Variante	Geeignet für	Zugriff	Eigener UI-Aufwand
Öffentliches Script-Widget	Website, Landingpage, einfache Einbindung	öffentlich freigegebener Assistent	sehr gering
Widget per iFrame	Portale, Login-geschützte Bereiche, kontrollierte Freigabe	JWT oder Assistant Access Link	gering
Eigenes Widget mit AI SDK	volle UI-Kontrolle, eigenes Frontend, Produktintegration	meist Assistant Access Link	hoch

Als Grundregel gilt:

Nutze die integrierten Widgets, wenn du schnell einbettbar bleiben willst.
Nutze Assistant Access Links, wenn Zugriff, Filter und Features serverseitig kontrolliert werden sollen.
Nutze das AI SDK, wenn du das komplette Frontend selbst bauen willst.

Integrierte Widgets

Im Bot-Frontend wird ein eigenständiges Bundle widget.js gebaut. Dieses Bundle kann direkt in fremde Websites geladen werden und registriert mehrere Custom Elements.

Für die meisten Websites ist das die einfachste Variante:

<script type="module" src="https://bot.clye.app/widget.js"></script>
<clye-bot-chat bot-id="123"></clye-bot-chat>

Dieses Element rendert die bekannte Chat-Bubble und hängt sie an den body der Seite. Im Code ist das die empfohlene öffentliche Standard-Einbindung.

Wichtige Attribute:

bot-id: numerische ID des Assistenten
side: "left" oder "right"
blend-mode: z. B. "normal" oder "difference"
dark: optional für dunkle Darstellung
domain: falls das Widget gegen eine andere Bot-Domain sprechen soll; diese Domain wird auch für Download-, Datei- und Bild-Links im eingebetteten Widget verwendet
style-url: alternative CSS-Datei für die Bubble

Hinweise zum aktuellen Panel-Design: Hinweise zum Dokumentzugriff:

In Einbettungen kann der Dokumentzugriff bewusst auf einen Link-only-Modus begrenzt sein. Dann sehen Nutzer Dokumente als verlinkte Quellen, ohne dass dieselbe Einbettung automatisch eine vollständige Dokumentansicht öffnet.
Ältere Assistenten-Konfigurationen mit hideDocuments werden in der Auswahl für den Dokumentzugriff konsistent als verborgen behandelt. Wenn Dokumente im Widget fehlen, prüfe deshalb zuerst die Einbettungs-Einstellungen des Assistenten.
Das geöffnete Chat-Panel zeigt oben einen kleinen Kopfbereich mit Titel, Untertitel, optionalem Profilbild und Schließen-Button.
Unter Einstellungen → Einbetten → Kopfzeile des Chat-Fensters kannst du jetzt separat steuern,
- ob als Titel der Name des Assistenten oder ein fester Titel verwendet wird,
- ob in der Kopfzeile das Profilbild des Assistenten oder ein generisches Bot-Symbol erscheint,
- und ob in der Sprechblase / im Launcher das Profilbild oder weiter das animierte Bot-Gesicht angezeigt wird.
Wenn du keinen eigenen Untertitel setzt, zeigt das Widget standardmäßig „Antwortet sofort“ an.
Bei abgeschlossenen Assistenten-Antworten erscheint unter der Nachricht zusätzlich eine kleine Meta-Zeile wie „KI-Assistent · vor 2 Min.“. Bei älteren Antworten wird stattdessen das Datum angezeigt.
Auf dunklen Seitenhintergründen zeigt der Launcher jetzt einen weißen Kreis und bleibt dadurch besser sichtbar. Auf hellen oder sehr hellen Hintergründen wechselt der Launcher automatisch zu einer dunkleren Darstellung, damit der Startbutton lesbar bleibt. Wenn sich das Farbschema der Seite ändert, misst das Widget den Launcher-Hintergrund erneut und passt den Kontrast automatisch neu an.
Auf Mobilgeräten öffnet sich das Widget jetzt sauber über die volle verfügbare Höhe des Bildschirms. Dabei berücksichtigt es Safe Areas wie Display-Aussparungen und den unteren Gerätebereich besser.
Im geöffneten Widget bleiben Nutzer-Nachrichten auf Mobilgeräten rechts ausgerichtet. Dadurch bleibt der Verlauf auch auf schmalen Displays klar zwischen Nutzer- und Assistenten-Beiträgen getrennt.
Wenn ein Assistent auf Mobilgeräten Auswahl-Chips aus ask-Rückfragen anzeigt, bleiben diese im Bereich der Nutzerseite ebenfalls rechts ausgerichtet. So wirken vorgeschlagene Antworten und eigene Nachrichten als zusammengehöriger Eingabebereich.
Im geöffneten Widget nutzt das Eingabefeld auf Mobilgeräten jetzt eine größere Schriftgröße, damit Browser nicht unnötig in das Formular hineinzoomen.
Auf Touch-Geräten setzt das Widget den Eingabefokus beim Öffnen nicht mehr automatisch in das Textfeld. Dadurch springt die Bildschirmtastatur nicht sofort auf, sondern erst dann, wenn Nutzer wirklich in das Eingabefeld tippen.

Praktisch heißt das: Wenn eure Seite eigenes HTML erlaubt, reicht oft schon das Script plus das Element.

Einbettung über die Connect-Oberfläche

Wenn du das Widget nicht manuell zusammenbauen willst, kannst du die Einbindung direkt in der Oberfläche starten. Unter Einstellungen → Einbetten findest du dafür die Connect-Ansicht.

Dort kannst du optional zuerst eine eigene Webflow-App hinterlegen. Trage dafür Client ID und Client Secret der App ein und speichere die Zugangsdaten. Zusätzlich kannst du jetzt pro Assistent eine eigene Redirect URI hinterlegen. Wenn das Feld leer bleibt, verwendet CLYE AI weiter die serverseitige Standard-Redirect-URI. Die Connect-Autorisierung nutzt danach diese assistentenspezifischen Webflow-Zugangsdaten statt einer globalen Standard-App. Das ist besonders dann hilfreich, wenn ein Assistent mit einer eigenen Webflow-Workspace-App oder mit einer abweichenden OAuth-Redirect-URL verbunden werden soll.

Die Schaltfläche Webflow verbinden bleibt dabei auch innerhalb längerer Beschreibungstexte gut lesbar. Dadurch ist klarer erkennbar, dass du an dieser Stelle direkt die Webflow-Autorisierung startest und keinen normalen Textlink öffnest.

Nach der Autorisierung zeigt dir Connect die verfügbaren Sites für genau diesen Assistenten an. Dort wählst du die Website bzw. Ziel-Seite aus, auf der das Widget eingebunden werden soll. Diese Auswahl ist vor allem dann hilfreich, wenn ein Assistent auf mehreren Seiten oder in mehreren Sites genutzt werden kann. Danach zeigt dir die Oberfläche den passenden Script-Einbau für die ausgewählte Seite an.

Typischer Ablauf:

Einstellungen → Einbetten öffnen.
Optional unter Eigene Webflow-App die Client ID, das Client Secret und bei Bedarf eine eigene Redirect URI deiner Webflow-App eintragen und auf Zugangsdaten speichern klicken.
Falls deine Webflow-App eine eigene Redirect-URL erwartet, prüfe vor dem Verbinden, dass genau diese URL auch in Webflow hinterlegt ist.
In Connect auf Webflow verbinden klicken.
Die gewünschte Site in Webflow autorisieren oder auswählen.
Danach in Connect die gewünschte Site / Seite auswählen.
Das angezeigte Script kopieren.
Das Script im HTML deiner Website einfügen.
Die Seite neu laden und prüfen, ob Bubble oder Chat wie erwartet erscheinen.

Wichtig für die Freigabe: Die Connect-Autorisierung startet nur mit Schreibrechten im jeweiligen Space. Außerdem muss der ausgewählte Assistent wirklich zu diesem Space gehören. Eigene Webflow-Zugangsdaten werden ebenfalls pro Assistent gespeichert; dazu gehört jetzt auch eine optional abweichende Redirect URI. Wenn du eine andere Site oder einen anderen Assistenten verbindest, übernimm den Script-Einbau deshalb jeweils neu aus der Connect-Oberfläche, damit Assistent, Zugangsdaten, Redirect-URL, Space und Zielseite sauber zusammenpassen.

Wenn Webflow nach der Freigabe zu CLYE AI zurückleitet, wird der Callback jetzt über den einmaligen, zeitlich begrenzten State der gestarteten Verbindung geprüft. Dadurch bleibt die Rückkehr auch dann gültig, wenn beim Cross-Site-Redirect keine lokale Session aus dem ursprünglichen Tab mehr mitgeschickt wird. Für dich heißt das praktisch: Solange du den Verbindungsdialog normal über Webflow verbinden gestartet hast und die Freigabe nicht abgelaufen ist, sollte die Autorisierung nicht an einer fehlenden lokalen Session scheitern.

Wichtig: Im eingebetteten Widget werden aktuell keine Quellen-Chips angezeigt. Wenn Antworten Datei-Links, Download-Links oder Bild-/Datei-Parts enthalten, nutzt das Widget dafür dieselbe domain, die auch für die Widget-API verwendet wird. Ohne gesetzte domain werden diese Links standardmäßig gegen die CLYE-Domain aufgelöst. Vom Agenten erzeugte Markdown-Links bleiben dabei klickbar.

Bei Hosted Apps, die Widget oder App-HTML direkt ausliefern, wird das geladene bundle.js jetzt wieder sauber an der vorgesehenen Stelle in das HTML eingesetzt. Wenn nach einem Deploy bisher nur ein leeres #root sichtbar war, obwohl das Bundle korrekt gebaut wurde, ist genau dieser Fall in der Doku jetzt mitgedacht.

Wenn eine Hosted App ihre Styles über import "./styles.css" lädt, wird das erzeugte bundle.css in Embed- und App-Vorschauen jetzt ebenfalls automatisch eingebunden. So erscheint die Vorschau nicht mehr ungestylt, obwohl das CSS korrekt mitgebaut wurde.

Wenn ein Assistent mit dem ask-Tool Auswahl-Chips für eine Rückfrage anbietet und ein Nutzer stattdessen eine freie Nachricht schreibt, zeigt das Widget dafür keine künstliche Antwortblase mit „abgebrochen“ mehr an. Die ursprüngliche Rückfrage des Assistenten bleibt im Verlauf sichtbar; nur die übersprungene Chip-Antwort erscheint nicht als scheinbar vom Nutzer geschriebene Nachricht.

Wenn eine ask-Rückfrage beantwortet wurde, zeigt das Widget diese Antwort jetzt im Verlauf wie eine normale Nutzer-Nachricht auf der Nutzerseite an. Die Antwort nutzt damit dieselbe Nachrichtenform wie andere eigene Eingaben und wirkt im Verlauf nicht mehr wie ein separates Sonderformat nur für ask.

Wenn ein Assistent nach einer ask-Rückfrage zusätzlich noch erklärenden Text sendet, rendert das Widget diesen Text jetzt wieder unterhalb der eigentlichen Assistenten-Antwort. So bleibt die Reihenfolge im Verlauf nachvollziehbar: erst die Antwortblase, danach der ergänzende Hinweistext des Assistenten.

Wichtig für eingebettete Chats: Bereits beantwortete oder übersprungene ask-Fragen bleiben auch nach dem Neuladen korrekt als erledigt erhalten. Offene Antwort-Chips erscheinen nur noch bei der aktuell letzten unbeantworteten ask-Nachricht. Ältere Rückfragen bleiben im Verlauf sichtbar, zeigen ihre Auswahl-Chips aber nicht mehr an und lassen sich deshalb nicht erneut aus älteren Stellen starten.

2. Direkte Bubble-Komponenten

Zusätzlich registriert widget.js niedrigere Bausteine:

clye-bot-bubble
clye-bot-bubble-open-shadow

Die beiden Varianten sind nützlich, wenn du die Bubble gezielter kontrollieren willst, zum Beispiel wenn du sie direkt in eine bestimmte Stelle im DOM einbetten willst, anstatt sie über das Portal-Verhalten von clye-bot-chat an den body anzuhängen.

Der Unterschied liegt im Shadow DOM:

clye-bot-bubble nutzt ein geschlossenes Shadow DOM (empfohlen, Styles sind isoliert)
clye-bot-bubble-open-shadow nutzt ein offenes Shadow DOM (nützlich, wenn du per JavaScript von außen in das Shadow DOM zugreifen musst)

<script type="module" src="https://bot.clye.app/widget.js"></script>
<clye-bot-bubble bot-id="123" side="right"></clye-bot-bubble>

Wichtige Attribute:

Attribut	Typ	Beschreibung
`bot-id`	Zahl	Numerische ID des Assistenten (Pflichtfeld)
`side`	`"left"` \| `"right"`	Auf welcher Seite die Bubble erscheint
`dark`	Boolean	Aktiviert die dunkle Darstellung
`style-url`	String	Pfad zu einer alternativen CSS-Datei
`domain`	String	Alternative Bot-Domain; wird auch für Download-, Datei- und Bild-Links im eingebetteten Widget verwendet

Der Unterschied zu clye-bot-chat: clye-bot-chat ist ein Portal-Element, das die Bubble selbst erzeugt und direkt an den document.body anhängt. clye-bot-bubble hingegen rendert an der Stelle im DOM, wo du das Element platzierst.

blend-mode wird bei clye-bot-bubble nicht als HTML-Attribut unterstützt. Für blend-mode nutze clye-bot-chat. Die automatische Kontrastanpassung für dunkle Hintergründe betrifft den Launcher von clye-bot-chat.

Für vordefinierte Einstiegsfragen gibt es zusätzlich:

<script type="module" src="https://bot.clye.app/widget.js"></script>
<clye-bot-question
  bot-id="123"
  label="Schnellstart"
  question="Wie kann ich helfen?"
  bot-question="Erkläre kurz, was du kannst."
></clye-bot-question>

Wichtige Attribute:

bot-id
label
question
bot-question
answers als JSON
domain

Wenn Nutzer:innen im Frage-Widget eine vorgegebene Antwort auswählen, erscheint diese Auswahl im Verlauf jetzt wie eine normale Nutzernachricht. Dadurch bleibt der Chat-Verlauf konsistent mit normalen Eingaben und Antwort-Auswahlen wirken nicht mehr wie ein separates Sonderformat.

Das ist sinnvoll, wenn nicht sofort ein vollständiger Chat erscheinen soll, sondern erst ein klarer Einstiegspunkt.

Das Bundle legt zusätzlich window.clyeBot an. Dort liegen die Web-Component-Konstruktoren für alle registrierten Elemente:

Eigenschaft	Registriert als	Beschreibung
`window.clyeBot.Chat`	(nicht vorregistriert)	Vollständige Chat-Ansicht ohne Bubble-Wrapper. Muss manuell registriert werden.
`window.clyeBot.Bubble`	`clye-bot-bubble`	Identisch mit dem gleichnamigen Custom Element
`window.clyeBot.Question`	`clye-bot-question`	Identisch mit dem gleichnamigen Custom Element

window.clyeBot.Chat ist der einzige Konstruktor, der nicht automatisch als Custom Element registriert wird. Das gibt dir die Möglichkeit, ihn unter einem eigenen Tag-Namen einzubinden:

<script type="module">
  import "https://bot.clye.app/widget.js";
  // eigener Tag-Name, weil clye-bot-chat bereits ein Portal-Element ist
  customElements.define("mein-chat", window.clyeBot.Chat);
</script>

<mein-chat bot-id="123"></mein-chat>

window.clyeBot.Chat rendert die Chat-Oberfläche direkt (ohne Bubble und Floating-Button). Unterstützte Attribute: bot-id (Zahl), domain (String).

Wenn du den Chat als komplette, kontrollierte Oberfläche einbetten willst, bleibt das iFrame-Widget der stabilste Weg:

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

Dafür gibt es zwei Token-Varianten:

JWT-Widget: gut für einfache, kurze Claims wie botId und exp
Assistant Access Link: besser für serverseitig erzwungene Filter, Features und längere Payloads

Wichtig für eingebettete Verläufe mit Assistant Access Link: Wenn derselbe Nutzer ein bestehendes Widget mit demselben gültigen Token oder Link erneut öffnet oder die Seite neu lädt, erscheint wieder der bisherige eigene Chat-Verlauf statt einer leeren neuen Unterhaltung. Sichtbar bleiben dabei nur die eigenen Chats, die über diesen Zugang zu genau diesem Assistenten entstanden sind. Für diese Berechtigungsprüfung zählt der Space des Assistenten. Normale Space-Berechtigungen werden dadurch nicht ausgehebelt; fremde Chats oder sonstige Inhalte außerhalb dieses Zugriffswegs bleiben weiterhin gesperrt.

Mehr dazu:

Eigene Chat-Widgets mit AI SDK

Wenn du das Frontend komplett selbst bauen willst, ist der relevante Pfad im Bot-Repo die Kombination aus:

@ai-sdk/react für useChat
ai für DefaultChatTransport
POST /api/chat als Backend-Endpunkt

Genau dieses Muster wird im Bot selbst verwendet, sowohl für eingebettete Chats als auch für normale Chat-Oberflächen.

Wann das sinnvoll ist

Ein eigenes Widget mit AI SDK ist sinnvoll, wenn du:

Design und UX vollständig selbst bestimmen willst
den Chat in eine bestehende Produktoberfläche integrieren willst
zusätzliche UI-Elemente wie Tabs, Formulare, Produktdaten oder Prozessschritte kombinieren willst
nicht an Bubble- oder iFrame-Layout gebunden sein willst

Wichtiger Unterschied zu JWT-Widgets

Für eigene AI-SDK-Frontends ist in der Regel der Assistant Access Link der richtige Zugriffspfad.

Der Grund: Das Chat-Backend leitet externe Sitzungen aus assistantAccessToken ab. Dieser Token wird im Request-Body mitgegeben. Das JWT-Widget ist dagegen primär für die Route /widget/{token} gedacht.

Wenn du im Assistenten unter Einstellungen → Einbetten → Widget Funktionen die Option Dokumente verbergen aktivierst, nutzt der eingebettete Assistent hochgeladene Dokumente nicht als Wissensquelle. In der Auswahl für den Dokumentenzugriff werden auch ältere Bots mit der bisherigen Einstellung hideDocuments konsistent als verborgen angezeigt. Zusätzlich bietet das Widget diese Dateien nicht zum Download an und verweist stattdessen nur auf gecrawlte Webseiten.

Wenn ihr statt vollständiger Dokumentzugriffe nur verlinkte Quellen zulassen wollt, kann der Dokumentzugriff im Embed zusätzlich auf einen Link-only-Modus begrenzt sein. In diesem Modus verweist das Widget auf die eigentliche Download- oder Ziel-URL, statt Dokumentinhalte direkt im eingebetteten Chat bereitzustellen.

Kurz gesagt:

iFrame auf /widget/{token}: JWT oder Assistant Access Link möglich
Eigenes Frontend auf /api/chat: bevorzugt Assistant Access Link verwenden

Markdown zusammen mit Widgets rendern

Wenn dein eigenes AI-SDK-Frontend Markdown und UI-Komponenten gemischt ausgibt, sollten Überschriften, Tabellen und Inline-Code auch dann korrekt als Markdown gerendert werden, wenn daneben Widgets oder andere Komponenten stehen. Betroffen sind typische Kombinationen wie Tabs, Cards, Alerts oder Accordions mit zusätzlichem Widget-Inhalt.

Gerade bei GFM-Tabellen in HTML- oder MDX-Slots darf zwischen aufeinanderfolgenden Tabellenzeilen keine zusätzliche Leerzeile stehen. Sonst wird die Tabelle oft schon nach der ersten Datenzeile beendet und weitere | ... |-Zeilen erscheinen als Rohtext.

Achte in eigenen Komponenten besonders auf diese Punkte:

Markdown nicht nur bei reinen Text-Kindern, sondern auch bei gemischten Bäumen aus Text und Widgets rendern
Leerzeilen in Slot- oder Container-Text nur vor dem Tabellenanfang erlauben, nicht zwischen aufeinanderfolgenden Tabellenzeilen
Tabs so rendern, dass TabsList, TabsTrigger und TabsContent auch während gestreamter Teil-Updates nicht kurz ohne ihren umschließenden Tabs-Kontext auftauchen
wenn einzelne Tab-Bausteine beim Streaming vorübergehend früher eintreffen, sollte die Oberfläche nicht auf „Komponente fehlgeschlagen“ umspringen, sondern die Tab-Leiste oder den Inhalt robust weiter anzeigen
Beispiele mit Überschrift + Widget + mehrzeiliger Tabelle + Hinweisbox testen, nicht nur reinen Fließtext

Wenn in einer eingebetteten Oberfläche Rohtext wie ##, Tabellen-Syntax oder `code` sichtbar bleibt, liegt die Ursache meist nicht am Inhalt selbst, sondern an der Render-Reihenfolge oder an übernommenen Leerzeilen innerhalb der verwendeten HTML- oder MDX-Komponenten. Bei Tabs zeigt sich ein ähnliches Muster: Kommen Tab-Leiste oder Tab-Inhalt beim Streaming kurz ohne vollständigen Wrapper an, sollte eure Oberfläche diese Zwischenphase tolerant behandeln statt die ganze Nachricht als defekte Komponente zu verwerfen.

Minimales React-Beispiel

Benötigte Version: Das Beispiel basiert auf AI SDK v5 (ai und @ai-sdk/react in derselben Major-Version, idealerweise beide auf ^5).

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";

type Props = {
  botId: number;
  assistantAccessToken?: string;
};

export function EmbeddedChat({ botId, assistantAccessToken }: Props) {
  const chat = useChat({
    transport: new DefaultChatTransport({
      api: "https://<deine-whitelabel-domain>/api/chat",
      body: {
        botId,
        ...(assistantAccessToken ? { assistantAccessToken } : {}),
      },
    }),
  });

  return (
    <div>
      <div>
        {chat.messages.map((message) => (
          <div key={message.id}>
            <strong>{message.role}:</strong> {message.parts?.map((p: any) => p.text).join("")}
          </div>
        ))}
      </div>

      <form
        onSubmit={(event) => {
          event.preventDefault();
          const formData = new FormData(event.currentTarget);
          const text = String(formData.get("message") || "");
          if (!text.trim()) return;
          chat.sendMessage({ text });
          event.currentTarget.reset();
        }}
      >
        <input name="message" placeholder="Nachricht..." />
        <button type="submit">Senden</button>
      </form>
    </div>
  );
}

Praxisbeispiel mit öffentlichem Assistenten (für alle freigegeben):

CodeSandbox: AI SDK mit öffentlichem Assistenten

Das Beispiel ist bewusst minimal. In der Praxis wirst du meist noch ergänzen:

Wenn ein KI-Budget ausgeschöpft ist, sollte dein eigenes Widget die vom Stream gelieferte Budget-Benachrichtigung als normalen Nachrichteninhalt anzeigen und nicht nur generische Fehler-Toasts auswerten. In CLYE erscheint die Meldung „AI-Budget aufgebraucht“ dafür direkt inline im Stream.

persistente chatId pro Session
eigenes Fehler-Handling
Wiederaufnahme laufender Streams
Uploads oder Tool-Interaktionen
eigenes Rendering für strukturierte Antworten und Tool-Calls

Was das Backend erwartet

Der Chat-Endpunkt akzeptiert unter anderem:

botId
messages oder newMessages
optional assistantAccessToken
optional id für eine persistente Chat-ID
Widget-Einstellungen des Assistenten, zum Beispiel Dokumente verbergen

Wenn ein assistantAccessToken gesetzt ist, wird serverseitig daraus eine minimale Widget-Session abgeleitet. Darüber können auch permissionFilter, loginUrl, features.chatHistory und Widget-Kontext aus dem Access Link wirksam werden.

Wenn dein eigenes Frontend mit seitengebundenen Formularen arbeitet, übergib zusätzlich die aktuelle Seiten-URL als pageUrl im Request-Body. Dadurch lesen Formular-Tools wie form_list und form_fill die Formulare der gerade geöffneten Seite direkt aus ihrem Live-HTML statt nur aus dem Crawl-Index. Das ist vor allem dann wichtig, wenn der Index für diese Seite keine Formulare enthält, obwohl im ausgelieferten HTML Formulare vorhanden sind.

Wenn Nutzer im Widget oder in einer gehosteten App einen Elementpicker verwenden, wird die Auswahl beim Absenden zusätzlich als Kontext an das Modell übergeben. Enthalten sind dabei der HTML-Pfad des gewählten Elements sowie – soweit vorhanden – id, relevante Klassen und der sichtbare Text. So kann der Assistent die konkrete Auswahl zuverlässiger einordnen, statt nur mit einer abstrakten Picker-Aktion zu arbeiten.

form_list gibt bei Treffern auf der aktuellen Seite nur diese Live-Formulare zurück
diese Einträge tragen onCurrentPage: true und können direkt mit form_fill genutzt werden
gibt es auf der aktuellen Seite kein Formular, meldet form_list das direkt für diese Seite
wenn die aktuelle Seite nicht gelesen werden kann, enthält der Hinweis die Ursache, zum Beispiel ungültige URL, kein HTML, Zeitüberschreitung oder zu viele Weiterleitungen
form_fill arbeitet im Widget nur mit Formularen der aktuellen Seite; Formulare anderer Seiten können beschrieben oder verlinkt, aber nicht in die aktuelle Seite eingetragen werden

Ein minimales Beispiel für den body im DefaultChatTransport:

body: {
  botId,
  pageUrl: window.location.href,
  ...(assistantAccessToken ? { assistantAccessToken } : {}),
}

Serverseitige Erzeugung des Access Links

Für eigene Widgets sieht der saubere Ablauf so aus:

Dein Portal oder Backend prüft die Anmeldung des Nutzers.
Dein Server ruft POST /api/assistant-link auf.
Die Antwort liefert token, url und jwtPayload.
Dein Frontend verwendet den token als assistantAccessToken für POST /api/chat.

Damit bleiben Berechtigungen, Filter und Ablaufzeit auf deiner Server-Seite kontrollierbar.

Welche Variante in der Praxis passt

Nutze das öffentliche Script-Widget, wenn eine Website schnell einen Assistenten bekommen soll.

Nutze das iFrame-Widget, wenn du die vorhandene Chat-Oberfläche übernehmen und nur kontrolliert einbetten willst.

Nutze ein eigenes AI-SDK-Widget, wenn der Chat Teil eures Produkts werden soll und visuell oder funktional stark an eure Anwendung angepasst werden muss.

Kurz gesagt

Die integrierten Widgets decken den schnellen Einbau ab. Für eine kontrollierte externe Nutzung ist meist der Assistant Access Link die beste Grundlage. Wenn du dagegen die Oberfläche selbst besitzen willst, orientiere dich am im Bot bereits verwendeten Muster aus useChat, DefaultChatTransport und POST /api/chat.

Chat einbetten und eigene Widgets

Überblick

Integrierte Widgets

1. Öffentliches Chat-Widget

Einbettung über die Connect-Oberfläche

2. Direkte Bubble-Komponenten

3. Frage-Widget

4. Web-Component-Konstruktoren aus dem Widget-Bundle

Widget per iFrame

Eigene Chat-Widgets mit AI SDK

Wann das sinnvoll ist

Wichtiger Unterschied zu JWT-Widgets

Markdown zusammen mit Widgets rendern

Minimales React-Beispiel

Was das Backend erwartet

Serverseitige Erzeugung des Access Links

Welche Variante in der Praxis passt

Kurz gesagt

Inhalt

Überblick​

Integrierte Widgets​

1. Öffentliches Chat-Widget​

Einbettung über die Connect-Oberfläche​

2. Direkte Bubble-Komponenten​

3. Frage-Widget​

4. Web-Component-Konstruktoren aus dem Widget-Bundle​

Widget per iFrame​

Eigene Chat-Widgets mit AI SDK​

Wann das sinnvoll ist​

Wichtiger Unterschied zu JWT-Widgets​

Markdown zusammen mit Widgets rendern​

Minimales React-Beispiel​

Was das Backend erwartet​

Serverseitige Erzeugung des Access Links​

Welche Variante in der Praxis passt​

Kurz gesagt​

Inhalt

Überblick

Integrierte Widgets

1. Öffentliches Chat-Widget

Einbettung über die Connect-Oberfläche

2. Direkte Bubble-Komponenten

3. Frage-Widget

4. Web-Component-Konstruktoren aus dem Widget-Bundle

Widget per iFrame

Eigene Chat-Widgets mit AI SDK

Wann das sinnvoll ist

Wichtiger Unterschied zu JWT-Widgets

Markdown zusammen mit Widgets rendern

Minimales React-Beispiel

Was das Backend erwartet

Serverseitige Erzeugung des Access Links

Welche Variante in der Praxis passt

Kurz gesagt