Widgets de ChatKit

Los widgets son los contenedores y componentes que incluye ChatKit. Puedes usar widgets prediseñados, modificar plantillas o diseñar tus propios widgets para personalizar por completo ChatKit en tu producto.

Diseña widgets rápidamente

Usa el Widget Builder de ChatKit Studio para probar distintos diseños de tarjetas y filas de listas y obtener una vista previa de los componentes. Cuando encuentres un diseño que te guste, copia el JSON generado en tu integración y sírvelo desde tu backend.

Sube recursos

Sube recursos para adaptar los widgets de ChatKit al diseño de tu producto. ChatKit requiere que alojes los archivos y las imágenes que subas en tu backend antes de hacer referencia a ellos en un mensaje. Consulta la guía de carga de archivos del SDK de Python para ver una implementación de referencia.

Los widgets de ChatKit pueden mostrar información de contexto, accesos directos y tarjetas interactivas directamente en la conversación. Cuando un usuario hace clic en un botón de un widget, tu aplicación recibe los datos de una acción personalizada para que puedas responder desde tu backend.

Procesa acciones en tu servidor

Con las acciones de los widgets, los usuarios pueden activar la lógica de tu aplicación desde la interfaz. Puedes asociar acciones a distintos eventos de los nodos de un widget (por ejemplo, al hacer clic en un botón) y procesarlas en tu servidor o en la integración del cliente.

Captura los eventos de los widgets con el callback onAction de WidgetsOption o con el hook equivalente de React. Envía los datos de la acción a tu backend para procesarla.

1
2
3
4
5
6
7
8
9
10
11chatkit.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 }),
      });
    },
  },
});

Encontrarás más información en la documentación sobre acciones.

Referencia

Te recomendamos empezar con los editores visuales y las herramientas anteriores. Consulta el resto de esta documentación para saber cómo funcionan los widgets y ver todas las opciones.

Cada widget se construye con un único contenedor (WidgetRoot) que contiene varios componentes (WidgetNode).

Contenedores (WidgetRoot)

Los contenedores tienen funciones específicas, como mostrar el texto de los indicadores de estado y las acciones principales.

• Card - Contenedor con límites definidos para los widgets. Admite los campos status, confirm y cancel para mostrar indicadores de estado y botones de acción debajo del widget.

  • children: list[WidgetNode]
  • size: “sm” | “md” | “lg” | “full” (valor predeterminado: “md”)
  • padding: float | str | dict[str, float | str] | None (claves: 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 – Muestra una lista vertical en la que cada elemento es un ListViewItem.

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

Componentes (WidgetNode)

ChatKit admite los siguientes tipos de widgets. También puedes explorar los componentes y usar un editor interactivo en la sección de componentes del Widget Builder.

• Badge – Etiqueta pequeña que muestra un estado o metadatos.

  • 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 – Contenedor flexible que permite definir la dirección, el espaciado y el estilo de los elementos.

  • 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 (claves: top, right, bottom, left, x, y)
  • margin: float | str | dict[str, float | str] | None (claves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borde único: { 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 – Distribuye los elementos secundarios en sentido horizontal.

  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None (claves: 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 (claves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borde único: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } por lado: { 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 – Distribuye los elementos secundarios en sentido vertical.

  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None (claves: 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 (claves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borde único: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } por lado: { 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 – Botón de acción configurable.

  • 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 – Texto complementario de menor tamaño.

  • 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 – Campo de fecha con un calendario desplegable.

  • 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 – Separador horizontal o vertical.

  • spacing: int | str | None
  • color: str | { dark: str, light: str } | None
  • size: int | str | None
  • flush: bool | None
  • key: str | None

• Icon – Muestra el ícono que indiques por su nombre.

  • name: str
  • color: str | { dark: str, light: str } | None
  • size: “xs” | “sm” | “md” | “lg” | “xl” | None
  • key: str | None

• Image – Muestra una imagen con opciones de estilo, ajuste y posición.

  • 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 (claves: 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 – Muestra una lista vertical de elementos.

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

• ListViewItem – Elemento de una lista ListView con una acción opcional.

  • children: list[WidgetNode] | None
  • onClickAction: ActionConfig | None
  • gap: int | str | None
  • align: “start” | “center” | “end” | “baseline” | “stretch” | None
  • key: str | None

• Markdown – Muestra texto con formato Markdown y admite actualizaciones en streaming.

  • value: str
  • streaming: bool | None
  • key: str | None

• Select – Campo desplegable que permite seleccionar una sola opción.

  • options: list[dict[str, str]] (cada opción: { 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 – Espacio vacío flexible para separar elementos en un diseño.

  • minSize: int | str | None
  • key: str | None

• Text – Muestra texto sin formato (usa Markdown para mostrar texto con formato Markdown). Admite actualizaciones en 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 (si es un diccionario: { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str })
  • key: str | None

• Title – Texto destacado para encabezados.

  • 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 – Contenedor que organiza los elementos y puede enviar una acción.

  • 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 (claves: top, right, bottom, left, x, y)
  • margin: float | str | dict[str, float | str] | None (claves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borde único: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } por lado: { 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 – Envuelve contenido que puede animarse.

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