Chat component

The Chat component is a UI element that enables interactive AI agent conversations with end-users within FlowX applications. It provides a conversational interface for AI-powered workflows and supports real-time message exchange between users and AI agents.

Overview

The Chat component serves as the primary interface for conversational AI experiences in FlowX. It allows users to interact with AI agents through natural language conversations, enabling use cases such as customer support, data collection, process guidance, and intelligent assistance.

Key features

Real-time messaging

Send and receive messages instantly with streaming support

AI agent integration

Connect to workflows powered by AI agents

Session management

Automatic session handling and persistence across page refreshes

Customizable UI

Themeable components with independent styling for agent and user messages

Message history

Retrieve and display conversation history on refresh

Knowledge Base integration

Ground AI responses in your organization’s data using RAG capabilities

Configurable welcome message

Personalized greetings using data from UI Flow data store

Configuration

Component setup

To add a Chat component to your UI Flow:

Navigate to UI Flows

Open your project and go to UI Flows from the left navigation menu.

Select or create a UI Flow

Select an existing UI flow or create a new one. This opens the UI Designer where you’ll see the Config and Runtime tabs at the top right for switching between configuration and preview modes.

Open UI Assets panel

In the left sidebar, expand the UI Assets panel. The Chat component is located alongside other common components like:

Table, Collection, Task Management, and Custom Components

Add Chat component

Select Chat from the UI Assets panel and drag it onto the canvas.

Configure properties

With the Chat component selected, use the right panel to configure:

Settings tab: Component properties like title, subtitle, workflow binding
Styles tab: Visual customization options

Required configuration

agentWorkflow

string

required

Agent ID / Workflow NameSpecify the workflow that will handle the chat interactions.

displayMode

string

Display Mode

Version	Available Modes
5.4	Full screen only
5.5+	Full screen, inline, modal, sidebar (planned)

workflowFormat

object

Workflow Input/Output FormatThe Chat component expects a defined input and output format within the connected workflow. The workflow must be configured to:

Accept the chat message as input
Return the agent response in the expected format

The workflow handles the communication between the Chat UI and the AI agent, processing user messages and returning appropriate responses.

welcomeMessage

string

Welcome MessageConfigure a customizable welcome message that displays when users first open the chat. The welcome message can be parameterized using values from the UI Flow data store.Example: "Hello ${customerName}, how can I help you today?"

The first message in the conversation typically comes from the AI agent. You can configure this greeting to be personalized based on user context stored in the data model.

Usage modes

The Chat component supports two usage modes:

Standalone component

Use the Chat as a dedicated full-screen experience, ideal for focused conversational interactions

Embedded in UI Flow

Embed the Chat within a larger UI Flow, combining it with other components like forms and displays

Component hierarchy

The Chat component consists of several configurable sub-components. In the UI Designer Navigation panel, the component hierarchy appears as:

📁 Chat
  ├── 📄 Header
  ├── 📁 Messages
  │     ├── 💬 Agent Message
  │     └── 💬 User Message
  └── ⌨️ Input

Each sub-component can be selected in the Navigation panel and configured individually using the Settings and Styles tabs in the right panel.

UI designer properties

Configure component behavior and content through the Settings tab in UI Designer (UI Flows → select a UI flow → select component):

Chat

Property	Description
Workflow	Select the workflow that handles chat interactions
Welcome Message	Initial greeting displayed when users open the chat (e.g., “Hello! How can I help you today?”)
Thinking Message	Text shown while the AI agent is processing a response (default: “Thinking…”)

The Advanced section contains the Data Test ID option for testing purposes.

Header

Property	Description
Button Label	Text for the “New chat” button (default: “New chat”)
Title	Main title text displayed in the header (e.g., “My chat”)
Subtitle	Secondary text below the title for additional context
Show Chat Icon	Toggle to display/hide the chat avatar icon
Show Separator	Toggle to display/hide the separator line below the header

Agent Message

Property	Description
Show Avatar	Toggle to display/hide the agent avatar icon

User Message

The User Message sub-component has no configurable properties in the Settings tab. Visual styling can be configured through Theme Admin.

Input

Property	Description
Placeholder	Hint text shown in the empty input field (e.g., “Ask me anything…”)

Theme configuration

Configure visual styling through Theme Admin (Design Assets → Themes → Components → Chat):

Chat

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	0
Border Width	Container border thickness	0 px
Border Radius	Corner rounding	0 px
Border Color	Border color	Transparent
Gap	Spacing between elements	0 px
Background Color	Container background	Shades (100)
Shadow	Drop shadow effect	None

Chat Header

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	16/0/0/16
Gap	Spacing between elements	8 px

Title:

Property	Description	Default
Text Style	Typography preset	Heading/H4 - bold
Text Color	Title text color	Neutrals (900)

Subtitle:

Property	Description	Default
Text Style	Typography preset	Paragraph/P1 - regular
Text Color	Subtitle text color	Neutrals (500)

Separator:

Property	Description	Default
Height	Separator thickness	1 px
Color	Separator color	Neutrals (200)

Icons:

Property	Description
Header Icon	Customizable chat avatar icon

Preview states: Default, Default (No Avatar), Default (No separator)

Messages

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	24/0/0/24
Border Width	Container border thickness	0 px
Border Color	Border color	Transparent
Border Radius	Corner rounding	0 px
Gap	Spacing between messages	8 px
Background Color	Messages area background	Shades (100)

Agent Message

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	0
Border Width	Message bubble border thickness	0 px
Border Color	Border color	Transparent
Border Radius	Corner rounding	0 px
Gap	Spacing between avatar and text	8 px
Background Color	Message bubble background	Transparent
Text Style	Typography preset	Paragraph/P1 - medium
Text Color	Message text color	Shades (900)

Icons:

Property	Description
Agent Icon	Customizable agent avatar icon

Preview states: Default, Default (No Avatar), Thinking, Thinking (No Avatar)

User Message

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	8/12/12/8
Border Width	Message bubble border thickness	1 px
Border Radius	Corner rounding	8 px
Border Color	Border color	Neutrals (200)
Background Color	Message bubble background	Neutrals (100)
Text Style	Typography preset	Paragraph/P1 - medium
Text Color	Message text color	Shades (900)

Preview states: Default

User Input Area

Common Properties:

Property	Description	Default
Padding	Spacing around content (4 sides)	16/16/16/16
Border Width	Container border thickness	1 px
Border Radius	Corner rounding	12 px
Border Color	Border color	Transparent
Background Color	Input area background	Neutrals (100)
Gap	Spacing between elements	8 px

Icons:

Property	Description
Send Message Icon	Customizable send button icon

Input

Common Properties:

Property	Description	Default
Font	Typography preset	Paragraph/P1 - regular
Accent Color	Focus/active accent color	Primary (500)

State-specific styling:

State	Properties
Default	Placeholder Color
Focused	Color, Placeholder Color
Disabled	Color, Placeholder Color
Filled	Color
Hovered	Color, Placeholder Color

Preview states: Default, Default (Disabled)

The Theme Admin provides a Web platform toggle, allowing you to preview and configure styles specifically for web applications.

All chat styling can be configured entirely within the Theme Admin area, allowing for consistent branding across your application. Changes are reflected in real-time in the preview panel.

Runtime behavior

Starting a chat

User initiates chat

User opens the chat from the UI Flow

API call

System calls the start chat API with the configured workflow

Session created

API returns a chatSessionId that is persisted for the user

Initial message

First message typically comes from the AI agent as a greeting or conversation starter

The initial system message can be configured in the workflow to provide a customized greeting or conversation starter.

Message exchange

Sending messages
Receiving messages

User types message in input field
Message is sent to the workflow via Chat Input node
Workflow processes the message through AI nodes
Response is returned to the chat interface

Session management

Session persistence

sessionId stored in browser session/local storage
Enables conversation continuity across page refreshes
Session data includes message history

Message history retrieval

On page refresh, system loads existing sessionId
Retrieves and displays previous messages
Restores conversation state automatically

Data storage

Chat sessions are persisted in the FlowX Database:

Each chat session is stored as a document containing the complete chat history. The chat component works with the FlowX Database to save chat sessions, where each session document contains the full conversation record.

Data Element	Storage Location	Description
Session ID	Browser storage + Database	Unique identifier linking client to server-side session
Message history	FlowX Database	Complete record of all messages in the conversation
Session metadata	FlowX Database	Timestamps, workflow reference, user information

Transparent persistence: Message persistence to the database is handled transparently by the platform. No additional configuration is required to enable chat history storage.

Custom chat persistence workflow

For advanced use cases where you need full control over chat session storage, you can build a custom workflow that manages chat persistence using FlowX Database. This approach allows you to:

Customize the chat data model
Add additional metadata to chat sessions
Integrate with external systems
Implement custom session management logic

Workflow overview

The chat persistence workflow handles two main scenarios:

Loading chat history - When a user returns to an existing chat session
Processing new messages - When a user sends a new message

Setting up the FlowX database data source

Create the data source

Navigate to Integrations → Data Sources → Add New Data Source and select FlowX Database.

Configure the collection

Name the collection (e.g., chat) and define the schema based on your data model.

Define the data model

Create a data model with the following structure:

Field	Type	Description
`chatSessionId`	string	Unique identifier for the chat session
`history`	array	List of message objects
`history[].actor`	string	Message sender (`human` or `agent`)
`history[].message`	string	The message content

Building the workflow

Create the workflow

Create a new workflow in Integration Designer with the following input parameters:

{
  "humanMessage": "",
  "action": "",
  "chatSessionId": ""
}

The action parameter determines whether to load history (LOAD_HISTORY) or process a new message.

Add Get chat session node

Add a Database Operation node to retrieve the existing session:

Property	Value
Operation	`db.chat.findOne`
Description	Chat session history
Parameter: chatSessionId	`${chatSessionId}`
Response Key	`chatSession`

Add action type condition

Add a Condition node to check the action type:

input.action == "LOAD_HISTORY"

If true: Route to the “Return chat history” end node
Else: Continue to message processing

Add Return chat history end node

For the LOAD_HISTORY branch, add an End Flow node that returns the chat history:

{
  "history": "${chatSession.data.history}"
}

Add session exists condition

For new messages, add another Condition node to check if the session exists:

input.chatSession.data == null

Add Create chat session node

If the session doesn’t exist, add a Database Operation node to create it:

Property	Value
Operation	`db.chat.insertOne`
Description	Create chat session
Parameter: chatSessionId	`${chatSessionId}`
Parameter: history	`[{ "actor": "human", "message": "${humanMessage}" }]`
Response Key	`responseKey`

Add Update history script node

If the session exists, add a Script node to append the new messages:

const history = input.chatSession.data.history;

const updatedHistory = [
  ...history,
  { actor: "human", message: input.humanMessage },
  { actor: "agent", message: input.agentMessage }
];

output.put("updatedHistory", updatedHistory);

Add Update chat session node

Add a Database Operation node to save the updated history:

Property	Value
Operation	`db.chat.updateOne`
Description	Update chat session
Parameter: chatSessionId	`${chatSessionId}`
Parameter: history	`${updatedHistory}`
Response Key	`responseKey`

Add Return response end node

Add an End Flow node that returns the response:

{
  "message": {
    "chatSessionId": "${chatSessionId}",
    "agentMessage": "${agentMessage}"
  }
}

Chat session data model example

Here’s an example of how a chat session document looks in the FlowX Database:

{
  "chatSessionId": "session-abc-123",
  "history": [
    {
      "actor": "human",
      "message": "Hello, I need help with my account"
    },
    {
      "actor": "agent",
      "message": "Hello! I'd be happy to help you with your account. What do you need assistance with?"
    },
    {
      "actor": "human",
      "message": "I want to update my email address"
    },
    {
      "actor": "agent",
      "message": "I can help you update your email address. Please provide your new email address."
    }
  ]
}

This custom workflow approach gives you full flexibility over chat data management. For most use cases, the transparent persistence provided by the platform is sufficient. Use custom workflows when you need to extend the default behavior or integrate with external systems.

UI Flow integration

The Chat component integrates seamlessly with UI Flows: Chat Component Wrapper

Chat component is embedded within UI Flow structure
Follows UI template hierarchy
Shares session context with other components

Communication with Other Components

Event-based communication

Components emit and listen for custom events
Enables loosely coupled interactions
Example: Chat triggers process start event

On-demand communication

Direct component-to-component calls
For tightly integrated features
Example: Chat updates task management state

Audit and debugging

UI Flows audit

Chat sessions tracking

All chat sessions are logged in UI Flow audit:

Track when chats are started
Monitor active and completed sessions
View session duration and message count

Console logging

Access detailed execution information:

View workflow execution logs
Debug conversation flow

Debug interface

UI Flow Sessions Console Access comprehensive debugging tools through the UI Flow Sessions panel:

Nodes
Logs
Input/Output
Documents

Track workflow execution with node-by-node timing:

Node	Typical Duration
Start	0 ms
Get chat session	~133 ms
Check action type	~52 ms
Return chat history	~60 ms

View detailed execution logs:

Workflow Run ID and timestamps
Triggered from: AUTOMATIC
Node execution start/finish events
Data Source operations (FlowX Database)
Collection: chat
Operations: db.chat.findOne - Chat session history
Status, Time, and Size metrics

Session status badges: Sessions display status badges like FINISHED to quickly identify completed conversations.

Theming

Theme elements

The Chat component supports comprehensive theming:

System theme
Custom themes

Default theme provided out-of-the-box
Includes chat-specific substitution tags
System media items for icons and avatars

Theme configuration

Theme Admin Interface Configure chat theming through the Theme Admin:

Visual theme editor with live preview
Save and apply custom themes
Consistent styling across all chat instances

CMS Migration When upgrading, the system handles:

System tags migration for chat elements
System icons migration
Themes migration from previous versions

SDK integration

The Chat component is available through the FlowX SDKs for both Angular and React applications. For detailed implementation guides, parameters, and configuration options, refer to the SDK documentation:

Angular SDK

Use the FlxChatRendererComponent in Angular applications

import { FlxChatRendererComponent } from '@flowx/angular-sdk';

React SDK

Use the FlxChatRenderer component in React applications

import { FlxChatRenderer } from '@flowx/react-sdk';

Key SDK parameters

Parameter	Description	Required
`apiUrl`	Your base FlowX API URL	✅
`authToken`	Authorization token from auth provider	✅
`projectId`	The FlowX project ID	✅
`workspaceId`	The workspace ID	✅
`source`	Source object with workflow type and ID	✅
`chatConfig`	Chat configuration object (welcome message, title, etc.)	❌
`themeId`	Theme identifier for styling	❌
`language`	Language for localization	❌

For the complete list of parameters, chatConfig options, and usage examples, see the respective SDK documentation pages linked above.

Best practices

Workflow design

Do

Keep chat workflows focused on a single use case
Use clear, natural language prompts
Test with various user inputs
Handle errors gracefully with helpful messages

Don't

Don’t create overly complex conversation flows
Don’t send responses from multiple Custom Agent nodes

User experience

Do

Provide clear initial greeting messages
Show typing indicators during processing
Display helpful error messages
Allow users to restart conversations
Maintain consistent agent personality

Don't

Don’t make users wait too long for responses
Don’t use technical jargon in agent messages
Don’t lose conversation context
Don’t hide important information

Performance

Do

Optimize workflow execution time
Cache frequently accessed data
Limit message history retrieval

Don't

Don’t load entire conversation history every time
Don’t make unnecessary API calls
Don’t process messages synchronously if avoidable

Troubleshooting

Chat not loading

Possible causes:

Workflow is not properly configured
Workflow is not published
UI Flow has incorrect agent ID/workflow name

Solutions:

Verify the workflow is properly configured
Check that the workflow is published and active
Ensure UI Flow has correct agent ID/workflow name

Messages not sending

Possible causes:

Network connectivity issues
Workflow is in error state
Configuration errors

Solutions:

Check network connectivity
Verify workflow is not in error state
Review workflow console logs for errors

Session lost on refresh

Possible causes:

sessionId is not persisted in storage
Browser storage permissions issues
Session management misconfiguration

Solutions:

Ensure sessionId is persisted in storage
Check browser storage permissions
Verify session management configuration

Roadmap

Version 5.5 (Planned)

File upload support

Allow users to upload files in chat conversations

Enhanced chat audit

Detailed session analytics and reporting

Additional display modes

Inline, modal, and sidebar display options

Improved debugging tools

Enhanced debugging and visualization

Mobile support

Chat component availability on iOS and Android

Future enhancements

Multi-language support: Built-in translation capabilities
Voice input/output: Speech-to-text and text-to-speech
Rich message types: Cards, carousels, buttons
Agent handoff: Transfer to human agents
Sentiment analysis: Real-time conversation monitoring

Knowledge Base integration

For grounded and consistent AI responses, the Chat component can leverage Knowledge Bases to provide contextual information to AI agents. The Knowledge Base is a crucial feature that provides grounded and consistent answers from agents.

How it works

Create Knowledge Base

Set up a Knowledge Base as a Data Source in Integration Designer and upload relevant content

Content processing

Documents are automatically split into “chunks” and indexed for semantic search

Link to Custom Agent

Connect the Knowledge Base to Custom Agent nodes in your workflow. The Knowledge Base is used to retrieve context before engaging the large language model.

Context retrieval

When a user sends a message, relevant chunks are retrieved based on semantic similarity and returned with a relevance score

Supported file formats

The Knowledge Base supports multiple file formats for content ingestion:

Format	Description
PDF	Standard PDF documents
Markdown	`.md` files with formatted text
Word	Microsoft Word documents (`.docx`)
Excel	Spreadsheet data (`.xlsx`)
PowerPoint	Presentation files (`.pptx`)
Images	Image files with text content

Configuration options

Option	Description
Minimum relevance	Set a threshold for chunk relevance scores (0-1). Fine-tune to filter out low-quality matches.
Number of responses	Limit how many relevant chunks are returned to the LLM
Content updates	Use scheduled jobs or workflows to dynamically append, update, or replace content. Changes are immediately reflected—no retraining needed.

Single Knowledge Base per run: Currently, you cannot configure multiple Knowledge Bases in a single workflow run. Each Custom Agent node can connect to one Knowledge Base.

Relevance scoring

The current relevance computation is semantic:

How semantic scoring works

Text is transformed into a number vector (embedding)
The system calculates the distance between the query vector and chunk vectors
This acts as a measure of synonymy—finding semantically similar content even with different wording

Future scoring enhancements (planned)

Keyword-based scoring: Match based on specific keywords
Question-answer pair scoring: Evaluate how well Q&A pairs work together
User-controlled similarity: More control over how similarity scores are calculated

Knowledge Bases provide Retrieval-Augmented Generation (RAG) capabilities, ensuring AI responses are grounded in your organization’s actual data rather than relying solely on the LLM’s training data.

Knowledge Base Documentation

See the complete Knowledge Base documentation for setup guides and best practices.

Platform availability

Web
Mobile

Available in v5.4.0 ✓

Full screen display mode
Complete feature set
Angular and React renderer support
Can be used as standalone component or embedded within a UI Flow

Custom Agent Node

Learn about Custom Agent nodes in Integration Designer

Knowledge Base

Configure knowledge bases for grounded AI responses

MCP Integration

Learn about MCP server integration

UI Designer

Explore UI Designer capabilities

​Overview

​Key features

Real-time messaging

AI agent integration

Session management

Customizable UI

Message history

Knowledge Base integration

Configurable welcome message

​Configuration

​Component setup

​Required configuration

​Usage modes

Standalone component

Embedded in UI Flow

​Component hierarchy

​UI designer properties

​Theme configuration

​Runtime behavior

​Starting a chat

​Message exchange

​Session management

Session persistence

Message history retrieval

​Data storage

​Custom chat persistence workflow

​Workflow overview

​Setting up the FlowX database data source

​Building the workflow

​Chat session data model example

​UI Flow integration

​Audit and debugging

​UI Flows audit

Chat sessions tracking

Console logging

​Debug interface

​Theming

​Theme elements

​Theme configuration

​SDK integration

Angular SDK

React SDK

​Key SDK parameters

​Best practices

​Workflow design

Do

Don't

​User experience

Do

Don't

​Performance

Do

Don't

​Troubleshooting

​Roadmap

​Version 5.5 (Planned)

File upload support

Enhanced chat audit

Additional display modes

Improved debugging tools

Mobile support

​Future enhancements

​Knowledge Base integration

​How it works

​Supported file formats

​Configuration options

​Relevance scoring

Knowledge Base Documentation

​Platform availability

​Related resources

Custom Agent Node

Knowledge Base

MCP Integration

UI Designer

Overview

Key features

Configuration

Component setup

Required configuration

Usage modes

Component hierarchy

UI designer properties

Theme configuration

Runtime behavior

Starting a chat

Message exchange

Session management

Data storage

Custom chat persistence workflow

Workflow overview

Setting up the FlowX database data source

Building the workflow

Chat session data model example

UI Flow integration

Audit and debugging

UI Flows audit

Debug interface

Theming

Theme elements

Theme configuration

SDK integration

Key SDK parameters

Best practices

Workflow design

User experience

Performance

Troubleshooting

Roadmap

Version 5.5 (Planned)

Future enhancements

Knowledge Base integration

How it works

Supported file formats

Configuration options

Relevance scoring

Platform availability

Related resources