Chat component

The Chat component enables interactive AI agent conversations with end-users within FlowX applications. This page covers runtime behavior, session management, and advanced integration patterns.

For UI configuration, settings, and styling, see the Chat component in UI Designer.

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

Message history

Retrieve and display conversation history on refresh

Knowledge Base integration

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

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

{
  "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?"
    }
  ]
}

UI Flow integration

The Chat component integrates 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

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

SDK integration

The Chat component is available through the FlowX SDKs for both Angular and React applications.

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 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

Don't

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

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

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

Solutions:

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

Knowledge Base integration

The Chat component can use Knowledge Bases to provide contextual, grounded AI responses.

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

Context retrieval

When a user sends a message, relevant chunks are retrieved based on semantic similarity

Supported file formats

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	Threshold for chunk relevance scores (0-1)
Number of responses	Limit how many relevant chunks are returned to the LLM
Content updates	Use workflows to dynamically append, update, or replace content

Knowledge Bases provide Retrieval-Augmented Generation (RAG) capabilities, ensuring AI responses are grounded in your organization’s actual 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

Chat UI configuration

Settings, styling, and theme configuration

Chat interface concepts

High-level integration patterns

Custom Agent Node

Custom Agent nodes in Integration Designer

Knowledge Base

Configure knowledge bases for grounded AI responses

Config-time agents

Agent Builder

Using agents

​Key features

Real-time messaging

AI agent integration

Session management

Message history

Knowledge Base integration

​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

​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

​Knowledge Base integration

​How it works

​Supported file formats

​Configuration options

Knowledge Base Documentation

​Platform availability

​Related resources

Chat UI configuration

Chat interface concepts

Custom Agent Node

Knowledge Base

Key features

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

SDK integration

Key SDK parameters

Best practices

Workflow design

User experience

Performance

Troubleshooting

Knowledge Base integration

How it works

Supported file formats

Configuration options

Platform availability

Related resources