Widgets do ChatKit

Widgets são os contêineres e componentes que o ChatKit oferece. Você pode usar widgets prontos, adaptar modelos ou criar seus próprios widgets para personalizar por completo o ChatKit no seu produto.

Crie widgets rapidamente

Use o Widget Builder do ChatKit Studio para experimentar layouts de cartões e linhas de lista e visualizar os componentes. Quando estiver satisfeito com o resultado, copie o JSON gerado para a sua integração e disponibilize-o pelo backend.

Faça upload de recursos

Faça upload de recursos para adaptar os widgets do ChatKit ao visual do seu produto. Hospede os arquivos e as imagens enviados no seu backend antes de fazer referência a eles em uma mensagem do ChatKit. Consulte o guia de upload do SDK para Python para ver uma implementação de referência.

Os widgets do ChatKit podem exibir informações de contexto, atalhos e cartões interativos diretamente na conversa. Quando o usuário clica em um botão do widget, seu aplicativo recebe um payload de ação personalizada. Com esses dados, você pode responder pelo backend.

Processe ações no servidor

As ações dos widgets permitem que os usuários acionem a lógica do aplicativo pela interface. Você pode associar ações a diferentes eventos nos nodes do widget, como cliques em botões, e processá-las no servidor ou na integração do cliente.

Capture os eventos do widget com o callback onAction de WidgetsOption ou com o hook equivalente do React. Encaminhe o payload da ação ao backend para que ele a processe.

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 }),
      });
    },
  },
});

Saiba mais na documentação sobre ações.

Referência

Recomendamos começar pelos editores visuais e pelas ferramentas apresentados acima. Consulte o restante desta documentação para entender como os widgets funcionam e conhecer todas as opções.

Cada widget tem um único contêiner (WidgetRoot), que reúne vários componentes (WidgetNode).

Contêineres (WidgetRoot)

Os contêineres oferecem recursos específicos, como exibir o texto de um indicador de status e apresentar ações principais.

• Card – Um contêiner que delimita a área dos widgets. Os campos status, confirm e cancel permitem exibir indicadores de status e botões de ação abaixo do widget.

  • children: list[WidgetNode]
  • size: “sm” | “md” | “lg” | “full” (padrão: “md”)
  • padding: float | str | dict[str, float | str] | None (chaves: 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 – Exibe uma lista vertical em que cada item é um 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)

O ChatKit oferece suporte aos tipos de widget a seguir. Você também pode explorar os componentes e usar um editor interativo na seção de componentes do Widget Builder.

• Badge – Um pequeno rótulo para indicar status ou exibir metadados.

  • 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 – Um contêiner flexível que permite configurar a direção, o espaçamento e o estilo do layout.

  • 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 (chaves: top, right, bottom, left, x, y)
  • margin: float | str | dict[str, float | str] | None (chaves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borda única: { 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 – Organiza os elementos filhos na horizontal.

  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None (chaves: 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 (chaves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borda única: { 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 – Organiza os elementos filhos na vertical.

  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None (chaves: 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 (chaves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borda única: { 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 – Um botão de ação flexível.

  • 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 de apoio em tamanho menor.

  • 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 – Um campo de data com calendário suspenso.

  • 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 – Um separador horizontal ou vertical.

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

• Icon – Exibe o ícone correspondente ao nome informado.

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

• Image – Exibe uma imagem com opções de estilo, ajuste e posicionamento.

  • 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 (chaves: 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 – Exibe uma lista vertical de itens.

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

• ListViewItem – Um item de uma ListView que pode ter uma ação associada.

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

• Markdown – Renderiza texto formatado em Markdown e aceita atualizações por streaming.

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

• Select – Uma lista suspensa que permite selecionar uma única opção.

  • options: list[dict[str, str]] (cada opção: { 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 – Insere um espaço vazio de tamanho flexível no layout.

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

• Text – Exibe texto simples (use Markdown para renderizar texto em Markdown). Aceita atualizações por 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 (quando o valor é um dicionário: { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str })
  • key: str | None

• Title – Exibe um título em destaque.

  • 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 – Um contêiner de layout que pode enviar uma ação.

  • 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 (chaves: top, right, bottom, left, x, y)
  • margin: float | str | dict[str, float | str] | None (chaves: top, right, bottom, left, x, y)
  • border: int | dict[str, Any] | None (borda única: { 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 – Envolve conteúdo que pode ser animado.

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