Temas y personalización en ChatKit

Después de seguir la guía de inicio rápido de ChatKit, aprende a cambiar el tema y personalizar el chat integrado. Para adaptarlo al estilo de tu aplicación, elige un tema claro u oscuro, define un color de acento, ajusta la densidad y redondea las esquinas.

Descripción general

Para personalizar el tema, pasa un objeto de opciones. Si seguiste la guía de inicio rápido de ChatKit para integrar ChatKit en tu frontend, usa la sintaxis de React que se muestra a continuación.

• React: pasa las opciones a useChatKit({...})
• Integraciones avanzadas: configura las opciones con chatkit.setOptions({...})

El objeto de opciones tiene la misma estructura en ambos tipos de integración.

Explorar las opciones de personalización

Visita ChatKit Studio para ver implementaciones de ChatKit en funcionamiento y probar sus herramientas interactivas de creación. Si prefieres aprender experimentando en lugar de leer, puedes empezar con estos recursos.

Explorar la interfaz de ChatKit

Ver ejemplos en funcionamiento

Cambiar el tema

Define los colores, la tipografía y otros detalles para que el chat tenga el mismo estilo que tu producto. En el siguiente ejemplo, activamos el modo oscuro, cambiamos los colores, redondeamos las esquinas, ajustamos la densidad de la información y elegimos la fuente.

Para ver todas las opciones del tema, consulta la referencia de la API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14const options = {
  theme: {
    colorScheme: "dark",
    color: {
      accent: {
        primary: "#2D8CFF",
        level: 2,
      },
    },
    radius: "round",
    density: "compact",
    typography: { fontFamily: "'Inter', sans-serif" },
  },
};

Personalizar el texto de la pantalla de inicio

Cambia el texto que aparece cuando el editor está vacío para indicarles a los usuarios qué pueden preguntar o ayudarlos a escribir su primer mensaje.

1
2
3
4
5
6
7
8const options = {
  composer: {
    placeholder: "Ask anything about your data…",
  },
  startScreen: {
    greeting: "Welcome to FeedbackBot!",
  },
};

Mostrar prompts iniciales en hilos nuevos

Sugiere ideas de prompts al inicio de una conversación para orientar a los usuarios sobre qué pueden preguntar o hacer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17const options = {
  startScreen: {
    greeting: "What can I help you build today?",
    prompts: [
      {
        name: "Check on the status of a ticket",
        prompt: "Can you help me check on the status of a ticket?",
        icon: "search",
      },
      {
        name: "Create Ticket",
        prompt: "Can you help me create a new support ticket?",
        icon: "write",
      },
    ],
  },
};

Agregar botones personalizados al encabezado

Con los botones personalizados del encabezado puedes agregar opciones de navegación, contexto o acciones relevantes para tu integración.

1
2
3
4
5
6
7
8
9
10
11
12const options = {
  header: {
    customButtonLeft: {
      icon: "settings-cog",
      onClick: () => openProfileSettings(),
    },
    customButtonRight: {
      icon: "home",
      onClick: () => openHomePage(),
    },
  },
};

Habilitar archivos adjuntos

La opción de adjuntar archivos está desactivada de forma predeterminada. Para habilitarla, agrega la configuración de archivos adjuntos. A menos que implementes un backend personalizado, debes usar la estrategia de carga hosted. Consulta la documentación del SDK de Python para saber cómo usar otras estrategias de carga con un backend personalizado.

También puedes definir cuántos archivos pueden adjuntar los usuarios a sus mensajes, de qué tamaño y de qué tipos.

1
2
3
4
5
6
7
8
9
10const options = {
  composer: {
    attachments: {
      uploadStrategy: { type: "hosted" },
      maxSize: 20 * 1024 * 1024, // 20 MB per file
      maxCount: 3,
      accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
    },
  },
};

Habilitar las @menciones en el editor con etiquetas de entidad

Permite que los usuarios etiqueten “entidades” personalizadas mediante @menciones. Así, las conversaciones pueden incluir más contexto y ser más interactivas.

• Usa onTagSearch para devolver una lista de entidades según la consulta ingresada.
• Usa onClick para manejar el evento que se produce al hacer clic en una entidad.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24const options = {
  entities: {
    async onTagSearch(query) {
      void query;
      return [
        {
          id: "user_123",
          title: "Jane Doe",
          group: "People",
          interactive: true,
        },
        {
          id: "document_123",
          title: "Quarterly Plan",
          group: "Documents",
          interactive: true,
        },
      ];
    },
    onClick: (entity) => {
      navigateToEntity(entity.id);
    },
  },
};

Personalizar la apariencia de las etiquetas de entidad

Usa widgets para personalizar lo que se muestra al pasar el cursor sobre una etiqueta de entidad. Cuando el usuario coloque el cursor sobre la etiqueta, muestra una vista previa detallada, como una tarjeta de presentación, el resumen de un documento o una imagen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const options = {
  entities: {
    async onTagSearch() {
      return [];
    },
    onRequestPreview: async (entity) => ({
      preview: {
        type: "Card",
        children: [
          { type: "Text", value: `Profile: ${entity.title}` },
          { type: "Text", value: "Role: Developer" },
        ],
      },
    }),
  },
};

Agregar herramientas personalizadas al editor

Mejora la productividad al permitir que los usuarios ejecuten acciones propias de la aplicación desde la barra del editor. La herramienta seleccionada se enviará al modelo como herramienta preferida.

1
2
3
4
5
6
7
8
9
10
11
12const options = {
  composer: {
    tools: [
      {
        id: "add-note",
        label: "Add Note",
        icon: "write",
        pinned: true,
      },
    ],
  },
};

Activar o desactivar secciones y funciones de la interfaz

Desactiva las secciones y funciones principales de la interfaz si necesitas personalizar las opciones del encabezado más de lo que permite la configuración disponible y quieres implementar tus propias opciones. Desactivar el historial puede ser útil si los hilos y el historial no tienen sentido en tu caso de uso, por ejemplo, en un chatbot de soporte.

1
2
3
4const options = {
  history: { enabled: false },
  header: { enabled: false },
};

Cambiar la configuración regional predeterminada

Si tienes un ajuste de idioma para toda la aplicación, puedes cambiar la configuración regional predeterminada. De forma predeterminada, ChatKit usa la configuración regional del navegador.

1
2
3const options = {
  locale: "de-DE",
};