diff --git a/content/en/docs/appstore/platform-supported-content/modules/genai/conversational-ui.md b/content/en/docs/appstore/platform-supported-content/modules/genai/conversational-ui.md index c7418e44bdf..cfd0103282e 100644 --- a/content/en/docs/appstore/platform-supported-content/modules/genai/conversational-ui.md +++ b/content/en/docs/appstore/platform-supported-content/modules/genai/conversational-ui.md @@ -8,13 +8,13 @@ description: "Describes the Conversational UI marketplace module that assists de ## Introduction {#introduction} -With the [Conversational UI module](https://marketplace.mendix.com/link/component/227931), you can create an AI-based chat user interface. It contains the needed data model, pages, snippets and building blocks to do so. You can integrate with any LLM and knowledge base to create your own full screen, sidebar or modal chat. It integrates with the Atlas framework and is the basis for the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926). It is also included in the [Blank GenAI App](https://marketplace.mendix.com/link/component/227934). +With the [Conversational UI module](https://marketplace.mendix.com/link/component/227931), you can create a GenAI-based chat user interface. It contains the needed data model, pages, snippets, and building blocks. You can integrate with any LLM and knowledge base to create your full-screen, sidebar, or modal chat. It integrates with the Atlas framework and is the basis for the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926). It is also included in the [Blank GenAI App](https://marketplace.mendix.com/link/component/227934) and the [Suppor Assistant Starter App](https://marketplace.mendix.com/link/component/231035). Mendix has produced a [Conversational AI Design Checklist](/howto/front-end/conversation-checklist/) which suggests some best practices for introducing conversational AI into your app. ### Typical Use Cases {#use-cases} -Typical use cases include the following: +Typical use cases for Conversational UI include the following: * Create a chat interface for users to chat with Large Language Models (LLM). * Allow users to switch between different implementations by switching providers. @@ -26,10 +26,10 @@ Typical use cases include the following: The Conversational UI module provides the following functionalities: * UI components that you can drag and drop onto your pages, for example: - * Layouts to have a sidebar or floating popup chat + * Layouts to have a sidebar or floating pop-up chat * Pages that you can use in your navigation for chat * Snippets that you can use directly on your pages, for example to display messages or a history sidebar - * A floating button that for opening a chat + * A floating button for opening a pop-up chat * Pages, snippets and logic to display and export token usage data (if enabled in GenAI Commons and supported by the GenAI Connector of choice) * Operations to set up your context, interact with the model, and add the data to be displayed in the UI * Domain model to store the chat conversations and additional information @@ -43,7 +43,7 @@ This module is intended to enable chat interactions between a user and an AI mod To use the Conversational UI module, your Mendix Studio Pro version must be [9.24.2](/releasenotes/studio-pro/9.24/#9242) or higher. -You must also ensure that you have the prerequisite modules that Conversational UI requires. The modules are included by default in the [Blank GenAI App](https://marketplace.mendix.com/link/component/227934) and the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926), otherwise you must install them yourself: +You must also ensure that you have the prerequisite modules that Conversational UI requires. The modules are included by default in the [Blank GenAI App](https://marketplace.mendix.com/link/component/227934), the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) and the [Support Assistant Starter App](https://marketplace.mendix.com/link/component/231035), otherwise you must install them yourself: * [Atlas Core](https://marketplace.mendix.com/link/component/117187) * [Data Widgets](https://marketplace.mendix.com/link/component/116540) @@ -51,7 +51,7 @@ You must also ensure that you have the prerequisite modules that Conversational * [Nanoflow Commons](https://marketplace.mendix.com/link/component/109515) * [Web Actions](https://marketplace.mendix.com/link/component/114337) -Finally, you must also install and configure a connector that is compatible with GenAI Commons. Mendix provides platform-supported integration with either [(Azure) OpenAI](/appstore/modules/genai/openai/) or [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). You can also integrate with custom models, by making them compatible with the [GenAI Commons](/appstore/modules/genai/commons/) Request and Response. +Finally, you must also install and configure a connector that is compatible with GenAI Commons. Mendix provides platform-supported integration with either [(Azure) OpenAI](/appstore/modules/genai/openai/) or [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). You can also integrate with custom models by making them compatible with the [GenAI Commons](/appstore/modules/genai/commons/) Request and Response. ## Installation {#installation} @@ -59,22 +59,24 @@ Follow the instructions in [Using Marketplace Content](/appstore/use-content/) t ## Configuration {#configuration} -To use Conversational UI in your app, you must perform the following tasks: +To use Conversational UI in your app, you must perform the following tasks in Studio Pro: -1. Configure the relevant [user roles](#module-roles). -2. Create a [chat context](#chat-context). -3. Associate a [provider](#provider-config) and create an [action microflow](#action-microflow). -4. Use the [pages](#pages-and-layouts) and [snippets](#snippets) to create your UI. +1. Add the relevant [module roles](#module-roles) to the user roles in the project security. +2. Create the [UI for the chat](#ui-components) in your app by using the [pages](#pages-and-layouts) and [snippets](#snippets) as a basis. +3. Make sure there is a [chat context](#chat-context) available on the page where the conversation should be shown. +4. Associate one or more [provider-configs](#provider-config) to the chat context. +5. Use a default [action microflow](#action-microflow) or create a custom flow that will be executed when the user clicks the **Send** button. +6. In the project theme settings, include the ConversationalUI module in the right order . Add it after Atlas_Core so the styling does not get overwritten (see [Ordering UI Resource Modules](/howto/front-end/customize-styling-new/#ordering-ui-resource-modules) for more information). +7. Optionally, [customize styling](#customize-styling) by overwriting variables and adding custom scss. Custom styling modules need to be loaded after ConversationalUI when ordering UI resources. -## Technical Reference {#technical-reference} -To help you work with the Conversational UI module, the following sections of this document list the available entities and activities that you can use in your application. +The main entities are shown for reference in the diagram below. For technical documentation, follow the steps in the [Technical reference](#technical-reference) section. {{< figure src="/attachments/appstore/use-content/modules/genai/conversational-ui/domain-model.png" alt="" width="50%">}} -### Module Roles {#module-roles} +### Configuring the Roles {#module-roles} -Make sure that the module role `User` is part of the user roles that are intended to chat with the model. Optionally, you can grant the `_addOn_ReadAll` role to admin roles, so that users with that role can read all messages. +Make sure that the module role `User` is part of the user roles that are intended to chat with the model. Optionally, you can grant the `_addOn_ReadAll` role to admin roles, so that users with that role can read all messages. A role for usage montoring is related only to the [Token monitor snippets](#snippet-token-monitor) and does not relate to the conversational snippets. | Module role | Description | | --- | --- | @@ -82,121 +84,172 @@ Make sure that the module role `User` is part of the user roles that are intende | `_addOn_ReadAll` | Role can be granted additionally. Users with both roles can read all chat data. | | `UsageMonitoring` | Can view and export all token usage data. This is related to a module role with the same name in the GenAI Commons module. | -### ChatContext {#chat-context} +### Creating the Chat UI {#ui-components} -The `ChatContext` is the central entity in the UI and microflows. It can only be viewed by the owner (see [Module Roles](#module-roles) for exceptions). The object needs to be created for every new chat interaction and comprises the `messages` that are sent to and received from the model. A `ProviderConfig` should be associated via `ChatContext_ProviderConfig_Active` in order to execute the correct [action microflow](#action-microflow). +A set of reusable pages, layouts, and snippets is included in this module to allow you to add the conversational UI to your app. -If you need additional attributes or associations on the `ChatContext`, use an extension entity that refers to the object which can then be retrieved and altered when needed (for example in the action microflow). The [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) shows an example of this approach. +#### Pages and Layouts {#pages-and-layouts} -#### Chat Context Operations {#chat-context-operations} +You can include the following pages in your navigation, or copy them to your module and modify them to suit your use case: -The following operations can be found in the toolbox for processing the [ChatContext](#chat-context): +* **ConversationalUI_FullScreenChat** - This page displays a centered chat interface on a full-screen responsive page. +* **ConversationalUI_Sidebar** - This page displays the chat interface on the right side with the full height. +* **ConversationalUI_PopUp** - This is a floating pop-up in the bottom-right corner. To open it, users can click the **Snippet_FloatingChatButton** that floats in the bottom-right corner. Alternatively, you can use the building block **Floating Chat Button** from the toolbox to create your custom opening logic. -* `Create ChatContext & Set ActionMicroflow` creates a new `ChatContext` and a new `ProviderConfig` (or a specialization of such depending on the input). The `ProviderConfig` is added to the `ChatContext` and set to active. Additionally, the action microflow of the new `ProviderConfig` is set. -* `Create ChatContext & Set ProviderConfig` creates a new `ChatContext` and sets a given `ProviderConfig` to active. -* `Create ChatContext & Set ProviderConfig (List)` creates a new `ChatContext` and adds a `ProviderConfig` to the `ChatContext` and sets it to active. In addition, a list of `ProviderConfigs` can be added to the `ChatContext` (non-active, but selectable in the UI). -* `Set ConversationID` sets the ConversationID on the `ChatContext`. Storing the ConversationID is needed for chat with history within Retrieve and Generate with [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). -* `Set Topic` sets the `Topic` of the `ChatContext`. This attribute can be used in the **History** sidebar while making historical chats visible to users. +All pages expect a [ChatContext](#chat-context) that needs to have an active [ProviderConfig](#provider-config). The user can chat with the LLM on all these pages, but cannot configure additional settings, such as the model or system prompt. There are many ways to enable this: on a custom page before the chat was opened, on a custom version of chat page itself, or in the [action microflow](#action-microflow) that is stored in the active [ProviderConfig](#provider-config). -#### Request Operations {#request-operations} +#### Snippets {#snippets} -* `Create Request from ChatContext` creates a [Request](/appstore/modules/genai/commons/) object that is used as input parameter in a `Chat with History` operation as part of the [action microflow](#action-microflow). For more information about the `Chat with History` operation, see [(Azure) OpenAI](/appstore/modules/genai/openai/) or [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). -* `Get Current User Prompt` gets the current user prompt. It can be used in the [action microflow](#action-microflow), because the `CurrentUserPrompt` from the chat context is no longer available. -* `Update Assistant Response` processes the response of the model and adds the new message and any sources to the UI. This is typically one of the last steps of the logic in an [action microflow](#action-microflow). +Drag the following snippets onto your other pages to quickly build your version of the chat interface. -#### Message {#message} +##### Chat Interface Snippets {#snippet-chat-interface} -A `Message` contains the content of both user and assistant messages, distinguishable by the `Role` attribute (such as User or Assistant). +Chat interface snippets contain the whole chat history as a list view and below that a text area for users to enter the user prompt. There are some UI components that show an error message when a call has failed, or that show progressing loading bots when waiting for the response. When a user clicks the **Send** button, the [action microflow](#action-microflow) is executed. -##### Source {#source} +The following versions are available and can be swapped as needed: -The model can return `Sources` which can be added to a message and displayed in the UI for the user. This can increase the understanding of the reasoning process, for example, why a model came up with a specific response. The content of the sources can come from a knowledge base or the model, depending on the implementation. +* **Snippet_ChatContext_ConversationalUI** - This snippet shows both the user messages and the responses on the left side of the container. +* **Snippet_ChatContext_ConversationalUI_Bubbles** - This snippet shows the user messages on the right side and the responses on the left side, similar to common chat apps. The content is placed inside colored cards (bubbles). -#### SuggestedUserPrompt {#suggested-user-prompt} +If the snippet does not fit your use case, you can [inline the snippet](/refguide/snippet-call/#inline-snippet) to customize it to your needs. -It is possible to add suggested user prompts to a `ChatContext`. They appear as a button for new chats. When a user clicks the **Suggested User Prompt** that appears above the chat input box, the [action microflow](#action-microflow) sends the content of the prompt to the model and starts a predefined chat in the interface. New `SuggestedUserPrompts` can be created and added to a `ChatContext` with the **Add SuggestedUserPrompt** toolbox action. +##### Message Snippets {#snippet-messages} -#### AdvancedSettings {#advanced-settings} +The messages snippets are already part of the [Chat Interface Snippets](#snippet-chat-interface), but can be used individually in your custom setup if needed. They contain the content of a single message, for example to be used in a list view. -`AdvancedSettings` can be used to allow users to configure parameters which can influence the model's behavior (see [Configuration Snippets](#snippet-configuration)). Currently, only temperature is exposed to users in the module by the slider input element. The object needs to be created when the chat context is shown to the page, for example in a navigation flow. Ranges can be set to control the values a user can select. +The following versions are available and can be swapped as needed: -### ProviderConfig {#provider-config} +* **Snippet_Message** - This snippet shows both the user messages and the responses on the left side of the list. +* **Snippet_Message_Bubble** - This snippet shows the user messages on the right side and the responses on the left side, similarly to common chat apps. The content is placed inside colored cards (bubbles). -The `ProviderConfig` contains the selection of the model provider for the AI Bot to chat with. This contains an action microflow that is executed when the **Send** button is clicked. You can store additional information, such as connection details, on the `ProviderConfig` by using a specialization and adding the necessary fields. For an example implementation, see the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926). +##### Advanced Configuration Snippets {#snippet-configuration} -The **Create ProviderConfig for ChatContext** toolbox action adds a new `ProviderConfig` (or a specialization of such depending on the input) to a `ChatContext`. The `ProviderConfig` can optionally also be set to active if `IsActive` is set to true. Additionally, the action microflow of the new `ProviderConfig` is set. +The following additional snippets can be used to give the user more control over the chat conversations. -#### Action Microflow {#action-microflow} +* **Snippet_ChatContext_AdvancedSettings** - This snippet can be placed on pages to let users configure specific parameters (currently **temperature**). Use the microflow **AdvancedSettings_GetAndUpdate** to set the boundaries and default value for advanced settings in the UI. +* **Snippet_ChatContext_SelectActiveProviderConfig** - With this snippet, users can select an active [Provider Config](#provider-config) from all associated configurations, for example, to let them select a model. +* **Snippet_ChatContext_HistorySideBar** - This snippet can be used in a list view to show past conversations. It displays the **topic** of the chat context as well as a delete icon on hover. For details on how to set the topic, see [ChatContext operations](#chatcontext-operations). -The `Action Microflow` is executed by clicking the **Send** button. It handles the interaction between the LLM connectors and the Conversational UI entities. An example for each are provided in The **USE_ME** folder included in the Conversational UI module contains example action microflows for both [OpenAI](/appstore/modules/genai/openai/) and [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). You can copy these microflows and modify them for your use cases, or use them directly for test purposes. +See the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) or the [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) on how to use those snippets. -##### Using the Action Microflow {#set-action-microflow} +### Providing the ChatContext {#chat-context} -Add the action microflow to an existing `ProviderConfig` by using the **Set ActionMicroflow** toolbox action. Note that the action does not commit the object, so you must also add a step to commit it after. +The `ChatContext` is the central entity in the pages and snippets above and represents a chat conversation with potentially many messages. It functions as the input for the action microflow executed when the user clicks the **Send** button. It can only be viewed by the owner (see [Module Roles](#module-roles) for exceptions). The object needs to be created for every new chat conversation and comprises the `messages` sent to and received from the model during a chat interaction. A `ProviderConfig` should be associated via `ChatContext_ProviderConfig_Active` to execute the correct [action microflow](#action-microflow). To do this in an ACT microflow that opens the chat page, see the **USE_ME** > **Pages** folder for more examples. -##### Creating a Custom Action Microflow +If you need additional attributes or associations on the `ChatContext`, use a specialization or an extension entity that refers to the object which can then be retrieved and altered when needed (for example in the action microflow). The [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) shows an example of the extension entity approach. -If you want to create your own custom action microflow, keep the following considerations in mind: +#### Chat Context Operations {#chat-context-operations} -* Only one input parameter of [ChatContext](#chat-context) is accepted. -* The return type needs to be a `Success` Boolean. -* Use the [request operations](#request-operations) to facilitate the interaction between the chat context and the model. -* When creating the `ProviderConfig`, use [Set ActionMicroflow](#set-action-microflow) to set the microflow. +Depending on the implementation, you can create this entity using a microflow that opens the page or using a datasource microflow on the page itself. The following are the operations in the toolbox for creating the ChatContext: -### Pages and Layouts {#pages-and-layouts} +* `New Chat` creates a new `ChatContext` and a new `ProviderConfig` (or specialization of such depending on the input). The `ProviderConfig` is added to the `ChatContext` and set to active. Additionally, the action microflow of the new `ProviderConfig` is set. +* `New Chat with Existing Config` creates a new `ChatContext` and sets a given `ProviderConfig` to active. +* `New Chat with Additional Configs` creates a new `ChatContext` and adds a `ProviderConfig` to the `ChatContext` and sets it to active. In addition, a list of `ProviderConfig` can be added to the `ChatContext` (non-active, but selectable in the UI). -You can include the following pages in your navigation, or copy them to your module and modify them to suit your use case: +#### SuggestedUserPrompt {#suggested-user-prompt} -* **ConversationalUI_FullScreenChat** - This page displays a centered chat interface on a full screen responsive page. -* **ConversationalUI_PopUp** - This is a floating pop-up in the bottom-right corner. To open it, users can click the **Snippet_FloatingChatButton** that floats in the bottom-right corner. Alternatively, you can use the building block **Floating Button OpenChat** from the toolbox to create your custom opening logic. -* **ConversationalUI_Sidebar** - This page displays the chat interface on the right side with the full height. +It is possible to add suggested user prompts to a `ChatContext`. They appear as a button for new chats. When a user clicks the **Suggested User Prompt** that appears above the chat input box, the [action microflow](#action-microflow) sends the content of the prompt to the model and starts a predefined chat in the interface. New `SuggestedUserPrompts` can be created and added to a `ChatContext` with the **Add SuggestedUserPrompt** toolbox action. -All pages expect a [ChatContext](#chat-context) that needs to have an active [ProviderConfig](#provider-config). The user can chat with the LLM on all pages, but not configure any additional settings, such as the model or system prompt. This needs to happen before the page was opened, for example, or in the [action microflow](#action-microflow) that is stored in the active [ProviderConfig](#provider-config). +### Associating the ProviderConfig {#provider-config} -### Snippets {#snippets} +The `ProviderConfig` contains the selection of the model provider with which the AI Bot can chat. It also refers to an action microflow that is executed when the **Send** button is clicked for a `ChatContext` that has the `ProviderConfig` associated. -Drag the following snippets onto your other pages to quickly build your own version of the chat interface. +A `ProviderConfig` (or specialization) can be added directly using the aforementioned [operations](#chat-context-operations) that create a new `ChatContext`. -#### Chat Interface Snippets {#snippet-chat-interface} +If the `ChatContext` however already exists and a new `ProviderConfig` needs to be added, use the **New Config for Chat** toolbox action. The `ProviderConfig` can optionally also be set to active if `IsActive` is set to true. Additionally, the action microflow of the new `ProviderConfig` is set. -Chat interface snippets contain the whole chat history as a list view, and below that a text area for users to enter the user prompt. There are some UI components that show an error message, when a call has failed, or that show progressing loading bots when waiting for the response. When a user clicks the **Send** button, the [action microflow](#action-microflow) is executed. +**ChatContext_AddProviderConfig_SetActive** is the counterpart of this flow when both the `ChatContext` and the `ProviderConfig` exist already. -The following versions are available and can be swapped as needed: +### Defining and Setting the Action Microflow {#action-microflow} -* **Snippet_ChatContext_ConversationalUI** - This snippet shows both the user messages and the responses on the left side of the container. -* **Snippet_ChatContext_ConversationalUI_Bubbles** - This snippet shows the user messages on the right side and the responses on the left side, similarly to common chat apps. The content is placed inside colored cards (bubbles). +The `Action Microflow` that is stored on a `ProviderConfig` is executed when the user clicks the **Send** button. This microflow handles the interaction between the LLM connectors and the Conversational UI entities. The **USE_ME** folder included in the Conversational UI module contains example action microflows for both [OpenAI](/appstore/modules/genai/openai/) and [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). You can copy these microflows and modify them for your use cases, or use them directly for test purposes. -If the snippet does not fit your use case, you can [inline the snippet](/refguide/snippet-call/#inline-snippet) to customize it to your needs. +Add the action microflow to an existing `ProviderConfig` by using the **Set Chat Action** toolbox action. Note that this action does not commit the object, so you must add a step to commit it afterward. -#### Message Snippets {#snippet-messages} +#### Creating a Custom Action Microflow -The messages snippets are already part of the [Chat Interface Snippets](#snippet-chat-interface), but can be used individually in your custom setup. They contain the content of the messages list view. +A typical action microflow is responsible for the following: +* Convert the `ChatContext` with user input to a `Request` structure for the chat completions operation. +* Retrieve the connection details (i.e. credentials, configuration, etc.) for the operation. +* Execute the chat completions operation for the LLM of choice. +* Update the `ChatContext` structure based on the response so that the user can see the result in the UI. -The following versions are available and can be swapped as needed: +If you want to create your custom action microflow, keep the following considerations in mind: -* **Snippet_Message** - This snippet shows both the user messages and the responses on the left side of the list. -* **Snippet_Message_Bubble** - This snippet shows the user messages on the right side and the responses on the left side, similarly to common chat apps. The content is placed inside colored cards (bubbles). +* Only one input parameter of [ChatContext](#chat-context) or a specialization is accepted. +* The return type needs to be a `Success` boolean. +* Use the [chat context](#chatcontext-operations) and [request operations](#request-operations) to facilitate the interaction between the chat context and the model. +* The custom action microflow can only be triggered if it is set as an action microflow for the `ProviderConfig` using one of the operations mentioned before. -#### Configuration Snippets {#snippet-configuration} +##### ChatContext operations {#chatcontext-operations} -* **Snippet_ChatContext_AdvancedSettings** - This snippet can be placed on pages to let users configure specific parameters (currently **temperature**). -* **Snippet_ChatContext_SelectActiveProviderConfig** - With this snippet, users can select an active [Provider Config](#provider-config) from all associated configurations, for example to let them select a model. -* **Snippet_ChatContext_HistorySideBar** - This snippet can be used in a list view of past conversations. +The following operations can be found in the toolbox for changing the [ChatContext](#chat-context) in a (custom) action microflow: +* `Set ConversationID` sets the ConversationID on the `ChatContext`. Storing the ConversationID is needed for a chat with history within Retrieve and Generate with [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). +* `Set Topic` sets the `Topic` of the `ChatContext`. This attribute can be used in the **History** sidebar while making historical chats visible to users. -See the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) or the [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) on how to use those snippets. +##### Request Operations {#request-operations} -#### Token Monitor Snippets {#snippet-token-monitor} +The following operations are used in a (custom) action microflow: -* **Snippet_TokenMonitor** - This snippet can be used to display token usage informatation in charts and contains several other snippets that you can use to build your own token monitor dashboard. To display the token usage data, users will need the `UsageMonitoring` userrole. -* **Snippet_TokenMonitor_Export** - This snippet can be used to display token usage informatation in a grid and export it as .xlsx. +* `Create Request from ChatContext` creates a [Request](/appstore/modules/genai/commons/) object that is used as an input parameter in a `Chat with History` operation as part of the [action microflow](#action-microflow). For more information about the `Chat with History` operation, see [(Azure) OpenAI](/appstore/modules/genai/openai/#chatcompletions-with-with-history) or [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/). +* `Get Current User Prompt` gets the current user prompt. It can be used in the [action microflow](#action-microflow) because the `CurrentUserPrompt` from the chat context is no longer available. +* `Update Assistant Response` processes the response of the model and adds the new message and any sources to the UI. This is typically one of the last steps of the logic in an [action microflow](#action-microflow). + +### Customizing styling {#customize-styling} + +The ConversationalUI module comes with its stylesheets that are intended to work on top of Atlas Core. You can use variables and custom classes to modify the default rendering, and think of colors, sizes, and positions. To learn more about customizing styling in a Mendix app in general and targeting elements using SCSS selectors, refer to the [how-to](/howto/front-end/customize-styling-new/#add-custom-styling) page. + +#### Variables {#customize-styling-variables} + +The following variables have a default value defined in the Conversational UI module. You can override the values by setting a custom value in the _custom-variables.scss file or your styling module. + +| Variable name | Description | +| --- | --- | +| `chat-width` | the max-width of the chat UI in a full-page setup | +| `send-btn-size` | the height and width of the button in the user chat input box | +| `chat-input-max-height` | the max-height of the user chat input box | +| `chat-header-color` | the background color of the topbar of the pop-up and sidebar chat window | +| `pop-up-chat-bottom-position` | the absolute bottom-position of the pop-up chat window | +| `pop-up-chat-right-position` | the absolute right-position of the pop-up chat window | +| `pop-up-chat-width` | the width of the pop-up and sidebar chat window | +| `pop-up-chat-height` | the height of the pop-up chat window | +| `chat-bubble-user-background` | the background color of a user message in the pop-up and sidebar chat | +| `chat-bubble-assistant-background` | the background color of an assistant message in the pop-up and sidebar chat | + +You can find the default values of these variables in the `_chat-variables.scss` file that is shipped with this module. + +#### Creating Custom SCSS {#customize-styling-classes} +You can use the following classes in your custom stylesheets to overwrite the default styling of Conversational UI and modify the behavior of the chat elements in your app. + +| Class name | Target element | +| --- | --- | +| `btn-chat-popup` | the floating button that opens the pop-up chat, also see `Snippet_FloatingChatButton` | +| `chat-container` | the container around the chat, including the input box and messages | +| `messages-container` | the container around the messages inside of `chat-container` | +| `send-btn` | the button in the user chat input box | +| `chat-btn-suggested-prompt` | a suggested prompt for the user to click instead of typing | +| `chat-input-wrapper` | the container around the user chat input box | +| `user-input-instructions` | the additional information text below the user chat input box | +| `message--assistant` | an assistant message in the conversation| +| `chat-bubble-wrapper--assistant` | an assistant message in the pop-up and sidebar chat | +| `message--user` | a user message in the conversation | +| `chat-bubble-wrapper--user` | a user message in the pop-up and sidebar chat | + +### Token Monitor Snippets {#snippet-token-monitor} + +A separate set of snippets has been made available to display and export token usage information in the running application. This is applicable for LLM connectors that follow the principles of [GenAI Commons](/appstore/modules/genai/commons/#token-usage) and as a result store token usage information. The following snippets can be added to (admin) pages independently from the conversation logic described in earlier sections. + +* **Snippet_TokenMonitor** - This snippet can be used to display token usage information in charts and contains several other snippets that you can use to build your token monitor dashboard. To display the token usage data, users will need the `UsageMonitoring` user role. +* **Snippet_TokenMonitor_Export** - This snippet can be used to display token usage information in a grid and export it as *.xlsx*. + +## Technical Reference {#technical-reference} -### Additional Operations {#operations} +The module includes technical reference documentation for the available entities, enumerations, activities, and other items that you can use in your application. You can view the information about each object in context by using the **Documentation** pane in Studio Pro. -The following additional microflows can be found in the **USE_ME** folder: +The **Documentation** pane displays the documentation for the currently selected element. To view it, perform the following steps: -* **ChatContext_AddProviderConfig_SetActive** - This microflow adds a `ProviderConfig` to the chat context and sets it to active. -* **ChatContext_Delete** - This microflow deletes a chat context. -* **AdvancedSettings_GetAndUpdate** - This microflow can be used after chat context creation to set the boundaries and default value for advanced settings in the UI. For more information, see [Configuration Snippets](#snippet-configuration). +1. In the [View menu](/refguide/view-menu/) of Studio Pro, select **Documentation**. +2. Click the element for which you want to view the documentation. ## Troubleshooting