Widgets ChatKit

Les widgets sont les conteneurs et les composants fournis avec ChatKit. Pour personnaliser entièrement ChatKit dans votre produit, vous pouvez utiliser des widgets prêts à l’emploi, adapter des modèles ou concevoir vos propres widgets.

Concevez rapidement des widgets

Utilisez le Widget Builder de ChatKit Studio pour essayer différentes dispositions de cartes et de lignes de liste, et prévisualiser les composants. Une fois la mise en page choisie, copiez le JSON généré dans votre intégration et servez-le depuis votre backend.

Importez des ressources

Importez des ressources pour adapter l’apparence des widgets ChatKit à celle de votre produit. Pour que ChatKit puisse les utiliser, votre backend doit héberger les fichiers et les images importés avant que vous y fassiez référence dans un message. Consultez le guide d’importation du SDK Python pour un exemple d’implémentation de référence.

Les widgets ChatKit peuvent afficher des informations contextuelles, des raccourcis et des cartes interactives directement dans la conversation. Lorsqu’un utilisateur clique sur un bouton de widget, votre application reçoit les données d’une action personnalisée, ce qui vous permet d’y répondre depuis votre backend.

Traitez les actions sur votre serveur

Les actions des widgets permettent aux utilisateurs de déclencher l’exécution de code depuis l’interface. Vous pouvez associer des actions à différents événements sur les nœuds d’un widget, par exemple à un clic sur un bouton, puis les traiter dans votre intégration côté serveur ou côté client.

Interceptez les événements des widgets avec la fonction de rappel onAction de WidgetsOption ou avec le hook React équivalent. Transmettez les données de chaque action à votre backend pour qu’il la traite.

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

Pour en savoir plus, consultez la documentation sur les actions.

Référence

Nous vous recommandons de commencer par les outils de conception visuelle présentés ci-dessus. La suite de cette documentation explique le fonctionnement des widgets et détaille les options disponibles.

Chaque widget se compose d’un seul conteneur (WidgetRoot), qui regroupe plusieurs composants (WidgetNode).

Conteneurs (WidgetRoot)

Les conteneurs offrent des fonctionnalités spécifiques, comme l’affichage d’un texte indiquant l’état du widget ou de boutons pour les actions principales.

• Card – Conteneur qui délimite une zone pour les widgets. Les champs status, confirm et cancel permettent d’afficher des indicateurs d’état et des boutons d’action sous le widget.

  • children : list[WidgetNode]
  • size : “sm” | “md” | “lg” | “full” (par défaut : “md”)
  • padding : float | str | dict[str, float | str] | None (clés : 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 – Affiche une liste verticale dont chaque élément est 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

Composants (WidgetNode)

ChatKit prend en charge les types de widgets suivants. Vous pouvez aussi parcourir les composants et les essayer dans un éditeur interactif depuis la section Composants du Widget Builder.

• Badge – Petit libellé qui indique un état ou affiche des métadonnées.

  • 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 – Conteneur de mise en page flexible dont vous pouvez régler l’orientation, l’espacement et le style.

  • 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 (clés : top, right, bottom, left, x, y)
  • margin : float | str | dict[str, float | str] | None (clés : top, right, bottom, left, x, y)
  • border : int | dict[str, Any] | None (bordure commune : { 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 – Dispose les éléments enfants horizontalement.

  • children : list[WidgetNode] | None
  • gap : int | str | None
  • padding : float | str | dict[str, float | str] | None (clés : 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 (clés : top, right, bottom, left, x, y)
  • border : int | dict[str, Any] | None (bordure commune : { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } par côté : { 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 – Dispose les éléments enfants verticalement.

  • children : list[WidgetNode] | None
  • gap : int | str | None
  • padding : float | str | dict[str, float | str] | None (clés : 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 (clés : top, right, bottom, left, x, y)
  • border : int | dict[str, Any] | None (bordure commune : { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } par côté : { 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 – Bouton d’action personnalisable.

  • 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 – Texte complémentaire affiché en plus petits caractères.

  • 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 – Champ de saisie de date avec calendrier déroulant.

  • 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 – Séparateur 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 – Affiche l’icône correspondant au nom indiqué.

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

• Image – Affiche une image. Vous pouvez en régler le style, l’ajustement au cadre et la position.

  • 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 (clés : 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 – Affiche une liste verticale d’éléments.

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

• ListViewItem – Élément d’une liste ListView auquel vous pouvez associer une action.

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

• Markdown – Affiche du texte mis en forme en Markdown et prend en charge les mises à jour en continu.

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

• Select – Liste déroulante permettant de sélectionner une seule option.

  • options : list[dict[str, str]] (pour chaque 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 – Réserve un espace vide de taille variable dans la mise en page.

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

• Text – Affiche du texte brut (utilisez Markdown pour le rendu Markdown). Prend en charge les mises à jour en continu.

  • 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 (pour un dictionnaire : { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str })
  • key : str | None

• Title – Affiche un titre bien visible.

  • 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 – Conteneur de mise en page qui peut déclencher une action à l’envoi du formulaire.

  • 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 (clés : top, right, bottom, left, x, y)
  • margin : float | str | dict[str, float | str] | None (clés : top, right, bottom, left, x, y)
  • border : int | dict[str, Any] | None (bordure commune : { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } par côté : { 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 – Enveloppe un contenu qui peut être animé.

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