Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

ChatKit-Widgets

So gestaltest du Widgets für deinen Chat.

Widgets sind die Container und Komponenten, die ChatKit mitliefert. Du kannst fertige Widgets verwenden, Vorlagen anpassen oder eigene Widgets entwerfen. So kannst du ChatKit ganz auf dein Produkt abstimmen.

Widgets

Widgets schnell entwerfen

Mit dem Widget Builder in ChatKit Studio kannst du Kartenlayouts und Listenzeilen ausprobieren und dir Komponenten in der Vorschau ansehen. Wenn dir ein Entwurf gefällt, kopiere das generierte JSON in deine Integration und stelle es über dein Backend bereit.

Dateien und Bilder hochladen

Lade Dateien und Bilder hoch, um ChatKit-Widgets an dein Produkt anzupassen. Für ChatKit muss dein Backend die hochgeladenen Dateien und Bilder bereitstellen, bevor du in einer Nachricht auf sie verweist. Eine Referenzimplementierung findest du in der Upload-Anleitung für das Python SDK.

ChatKit-Widgets können Kontext, Schnellzugriffe und interaktive Karten direkt im Chat anzeigen. Klickt jemand auf eine Schaltfläche im Widget, erhält deine Anwendung eine benutzerdefinierte Aktions-Payload. Darauf kannst du in deinem Backend reagieren.

Aktionen auf deinem Server verarbeiten

Über Widget-Aktionen können Personen direkt in der Benutzeroberfläche Anwendungslogik auslösen. Du kannst Aktionen an verschiedene Ereignisse auf unterschiedlichen Widget-Nodes binden, etwa an Klicks auf eine Schaltfläche. Die Aktionen kannst du anschließend auf deinem Server oder in deiner Client-Integration verarbeiten.

Erfasse Widget-Ereignisse mit dem onAction-Callback von WidgetsOption oder einem entsprechenden React-Hook. Leite die Aktions-Payload zur Verarbeitung an dein Backend weiter.

chatkit.setOptions({
  widgets: {
    async onAction(action, item) {
      await fetch("/api/widget-action", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ action, itemId: item.id }),
      });
    },
  },
});

Suchst du ein vollständiges Serverbeispiel? Die Dokumentation zum ChatKit Python SDK führt dich Schritt für Schritt durch die gesamte Implementierung.

Mehr dazu findest du in der Dokumentation zu Aktionen.

Referenz

Für den Einstieg empfehlen wir die oben vorgestellten visuellen Editoren und Werkzeuge. Im Folgenden erfährst du, wie Widgets funktionieren und welche Optionen dir zur Verfügung stehen.

Jedes Widget hat genau einen Container (WidgetRoot), der mehrere Komponenten (WidgetNode) enthält.

Container (WidgetRoot)

Container haben eigene Eigenschaften. Sie können beispielsweise Statustext anzeigen und primäre Aktionen anbieten.

  • Card bildet einen abgegrenzten Bereich für Widgets. Mit den Feldern status, confirm und cancel kannst du Statusanzeigen und Aktionsschaltflächen unter dem Widget anzeigen.

    • children: list[WidgetNode]
    • size: “sm” | “md” | “lg” | “full” (Standard: “md”)
    • padding: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • background: str | { dark: str, light: str } | None
    • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
    • collapsed: bool | None
    • asForm: bool | None
    • confirm: { label: str, action: ActionConfig } | None
    • cancel: { label: str, action: ActionConfig } | None
    • theme: “light” | “dark” | None
    • key: str | None
  • ListView zeigt eine vertikale Liste an, in der jeder Eintrag ein ListViewItem ist.

    • children: list[ListViewItem]
    • limit: int | “auto” | None
    • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
    • theme: “light” | “dark” | None
    • key: str | None

Komponenten (WidgetNode)

ChatKit unterstützt die folgenden Widget-Typen. In der Komponentenübersicht des Widget Builders kannst du die Komponenten auch durchsehen und in einem interaktiven Editor ausprobieren.

  • Badge zeigt eine kleine Beschriftung für Statusangaben oder Metadaten an.

    • label: str
    • color: “secondary” | “success” | “danger” | “warning” | “info” | “discovery” | None
    • variant: “solid” | “soft” | “outline” | None
    • pill: bool | None
    • size: “sm” | “md” | “lg” | None
    • key: str | None
  • Box ist ein flexibler Layout-Container, bei dem du Richtung, Abstände und Darstellung festlegen kannst.

    • children: list[WidgetNode] | None
    • direction: “row” | “column” | None
    • align: “start” | “center” | “end” | “baseline” | “stretch” | None
    • justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
    • wrap: “nowrap” | “wrap” | “wrap-reverse” | None
    • flex: int | str | None
    • height: float | str | None
    • width: float | str | None
    • minHeight: int | str | None
    • minWidth: int | str | None
    • maxHeight: int | str | None
    • maxWidth: int | str | None
    • size: float | str | None
    • minSize: int | str | None
    • maxSize: int | str | None
    • gap: int | str | None
    • padding: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • margin: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • border: int | dict[str, Any] | None (einheitlicher Rahmen: { size: int, color?: str | { dark: str, light: str }, style?: “solid” | “dashed” | “dotted” | “double” | “groove” | “ridge” | “inset” | “outset” } per-side: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict })
    • radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
    • background: str | { dark: str, light: str } | None
    • aspectRatio: float | str | None
    • key: str | None
  • Row ordnet untergeordnete Elemente horizontal an.

    • children: list[WidgetNode] | None
    • gap: int | str | None
    • padding: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • align: “start” | “center” | “end” | “baseline” | “stretch” | None
    • justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
    • flex: int | str | None
    • height: float | str | None
    • width: float | str | None
    • minHeight: int | str | None
    • minWidth: int | str | None
    • maxHeight: int | str | None
    • maxWidth: int | str | None
    • size: float | str | None
    • minSize: int | str | None
    • maxSize: int | str | None
    • margin: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • border: int | dict[str, Any] | None (einheitlicher Rahmen: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } je Seite: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict })
    • radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
    • background: str | { dark: str, light: str } | None
    • aspectRatio: float | str | None
    • key: str | None
  • Col ordnet untergeordnete Elemente vertikal an.

    • children: list[WidgetNode] | None
    • gap: int | str | None
    • padding: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • align: “start” | “center” | “end” | “baseline” | “stretch” | None
    • justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
    • wrap: “nowrap” | “wrap” | “wrap-reverse” | None
    • flex: int | str | None
    • height: float | str | None
    • width: float | str | None
    • minHeight: int | str | None
    • minWidth: int | str | None
    • maxHeight: int | str | None
    • maxWidth: int | str | None
    • size: float | str | None
    • minSize: int | str | None
    • maxSize: int | str | None
    • margin: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • border: int | dict[str, Any] | None (einheitlicher Rahmen: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } je Seite: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict })
    • radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
    • background: str | { dark: str, light: str } | None
    • aspectRatio: float | str | None
    • key: str | None
  • Button ist eine flexibel konfigurierbare Aktionsschaltfläche.

    • submit: bool | None
    • style: “primary” | “secondary” | None
    • label: str
    • onClickAction: ActionConfig
    • iconStart: str | None
    • iconEnd: str | None
    • color: “primary” | “secondary” | “info” | “discovery” | “success” | “caution” | “warning” | “danger” | None
    • variant: “solid” | “soft” | “outline” | “ghost” | None
    • size: “3xs” | “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | None
    • pill: bool | None
    • block: bool | None
    • uniform: bool | None
    • iconSize: “sm” | “md” | “lg” | “xl” | “2xl” | None
    • key: str | None
  • Caption zeigt ergänzenden Text in kleinerer Schrift an.

    • value: str
    • size: “sm” | “md” | “lg” | None
    • weight: “normal” | “medium” | “semibold” | “bold” | None
    • textAlign: “start” | “center” | “end” | None
    • color: str | { dark: str, light: str } | None
    • truncate: bool | None
    • maxLines: int | None
    • key: str | None
  • DatePicker ist ein Eingabefeld für Datumsangaben mit ausklappbarem Kalender.

    • onChangeAction: ActionConfig | None
    • name: str
    • min: datetime | None
    • max: datetime | None
    • side: “top” | “bottom” | “left” | “right” | None
    • align: “start” | “center” | “end” | None
    • placeholder: str | None
    • defaultValue: datetime | None
    • variant: “solid” | “soft” | “outline” | “ghost” | None
    • size: “3xs” | “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | None
    • pill: bool | None
    • block: bool | None
    • clearable: bool | None
    • disabled: bool | None
    • key: str | None
  • Divider zeigt eine horizontale oder vertikale Trennlinie an.

    • spacing: int | str | None
    • color: str | { dark: str, light: str } | None
    • size: int | str | None
    • flush: bool | None
    • key: str | None
  • Icon zeigt das Symbol mit dem angegebenen Namen an.

    • name: str
    • color: str | { dark: str, light: str } | None
    • size: “xs” | “sm” | “md” | “lg” | “xl” | None
    • key: str | None
  • Image zeigt ein Bild an. Optional kannst du festlegen, wie es aussieht, wie es in den verfügbaren Platz eingepasst wird und wo es erscheint.

    • size: int | str | None
    • height: int | str | None
    • width: int | str | None
    • minHeight: int | str | None
    • minWidth: int | str | None
    • maxHeight: int | str | None
    • maxWidth: int | str | None
    • minSize: int | str | None
    • maxSize: int | str | None
    • radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
    • background: str | { dark: str, light: str } | None
    • margin: int | str | dict[str, int | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • aspectRatio: float | str | None
    • flex: int | str | None
    • src: str
    • alt: str | None
    • fit: “none” | “cover” | “contain” | “fill” | “scale-down” | None
    • position: “center” | “top” | “bottom” | “left” | “right” | “top left” | “top right” | “bottom left” | “bottom right” | None
    • frame: bool | None
    • flush: bool | None
    • key: str | None
  • ListView zeigt Einträge als vertikale Liste an.

    • children: list[ListViewItem] | None
    • limit: int | “auto” | None
    • status: dict[str, Any] | None (Struktur: { text: str, favicon?: str })
    • theme: “light” | “dark” | None
    • key: str | None
  • ListViewItem ist ein Eintrag in einer ListView, dem du optional eine Aktion zuweisen kannst.

    • children: list[WidgetNode] | None
    • onClickAction: ActionConfig | None
    • gap: int | str | None
    • align: “start” | “center” | “end” | “baseline” | “stretch” | None
    • key: str | None
  • Markdown stellt Text mit Markdown-Formatierung dar und unterstützt Aktualisierungen per Streaming.

    • value: str
    • streaming: bool | None
    • key: str | None
  • Select ist eine Dropdown-Liste zur Auswahl einer einzelnen Option.

    • options: list[dict[str, str]] (je Option: { label: str, value: str })
    • onChangeAction: ActionConfig | None
    • name: str
    • placeholder: str | None
    • defaultValue: str | None
    • variant: “solid” | “soft” | “outline” | “ghost” | None
    • size: “3xs” | “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | None
    • pill: bool | None
    • block: bool | None
    • clearable: bool | None
    • disabled: bool | None
    • key: str | None
  • Spacer fügt einen flexiblen Zwischenraum in ein Layout ein.

    • minSize: int | str | None
    • key: str | None
  • Text zeigt unformatierten Text an (verwende Markdown für die Darstellung von Markdown). Die Komponente unterstützt Aktualisierungen per Streaming.

    • value: str
    • color: str | { dark: str, light: str } | None
    • width: float | str | None
    • size: “xs” | “sm” | “md” | “lg” | “xl” | None
    • weight: “normal” | “medium” | “semibold” | “bold” | None
    • textAlign: “start” | “center” | “end” | None
    • italic: bool | None
    • lineThrough: bool | None
    • truncate: bool | None
    • minLines: int | None
    • maxLines: int | None
    • streaming: bool | None
    • editable: bool | dict[str, Any] | None (bei Verwendung eines dict: { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str })
    • key: str | None
  • Title zeigt eine hervorgehobene Überschrift an.

    • value: str
    • size: “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “5xl” | None
    • weight: “normal” | “medium” | “semibold” | “bold” | None
    • textAlign: “start” | “center” | “end” | None
    • color: str | { dark: str, light: str } | None
    • truncate: bool | None
    • maxLines: int | None
    • key: str | None
  • Form ist ein Layout-Container, der beim Absenden eine Aktion auslösen kann.

    • onSubmitAction: ActionConfig
    • children: list[WidgetNode] | None
    • align: “start” | “center” | “end” | “baseline” | “stretch” | None
    • justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
    • flex: int | str | None
    • gap: int | str | None
    • height: float | str | None
    • width: float | str | None
    • minHeight: int | str | None
    • minWidth: int | str | None
    • maxHeight: int | str | None
    • maxWidth: int | str | None
    • size: float | str | None
    • minSize: int | str | None
    • maxSize: int | str | None
    • padding: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • margin: float | str | dict[str, float | str] | None (Schlüssel: top, right, bottom, left, x, y)
    • border: int | dict[str, Any] | None (einheitlicher Rahmen: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } je Seite: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict })
    • radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
    • background: str | { dark: str, light: str } | None
    • key: str | None
  • Transition umschließt Inhalte, die animiert werden können.

    • children: WidgetNode | None
    • key: str | None