Skip to main content
The Chat component enables interactive AI agent conversations with end-users within FlowX apps. 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

Reasoning transparency

Show AI reasoning steps to users for trust and transparency

​
Display types

When adding a Chat component, you choose a Chat Display Type that determines how the chat renders within your app.
Chat Display Type
Renders within the parent component, filling the available space.
  • Can be a child of any container or card
  • Embeds directly into the page layout
  • Best for dedicated chat pages or inline chat experiences
You can change the chat display type after creation if needed.

​
Global component

Available starting with FlowX.AI 5.5.0
The Chat component can be added as a Global Component in UI Flows, making it persist across pages without needing to add it to each page individually. When configured as a global component:
  • The chat appears in the Global Components section of the left navigation panel
  • It persists as users navigate between pages in the UI Flow
  • You can attach or detach the chat from specific pages to control where it appears
  • The chat maintains its conversation state across page navigation
To add Chat as a global component, click + in the Global Components section of the UI Flow navigation panel, then select Chat and configure its display type (Inline or Overlay).
Use Global Components when you want the chat to be available throughout the entire app experience without re-adding it to every page.

​
Sizing

The Chat component and floating action button support fixed sizing, allowing you to set a specific width and/or height value for precise control over the chat container dimensions.

​
Subcomponents

Enhanced in FlowX.AI 5.5.0The Chat component includes specialized subcomponents for reasoning display, error handling, and message regeneration.
The Chat component is composed of the following subcomponents:
SubcomponentDescription
HeaderConfigurable header with avatar, title, subtitle, new chat button, fullscreen toggle, and dock/collapse controls
MessagesMessage display with sender/receiver differentiation, markdown rendering, and avatar support
ReasoningDisplays AI reasoning steps (thinking indicators) during response generation
InputMessage input field with configurable placeholder and multiline support

​
Reasoning display

The reasoning subcomponent shows users how the AI agent is processing their request. When enabled, a thinking indicator appears while the agent works through its reasoning steps.
PropertyDescription
reasoningToggle to show/hide reasoning steps in the chat
thinkingMessageCustom message to display during reasoning (e.g., “Thinking…”)

​
Error handling and regeneration

When a message fails to generate, the chat displays an error state with an option to retry:
PropertyDescription
errorMessageCustom error message to display on failure
canRegenerateEnable the regenerate button on failed messages
regenerateLabelCustom label for the regenerate button

​
Chat configuration

The chatConfig object controls the behavior and appearance of the chat:
PropertyTypeDescription
welcomeMessagestringInitial message shown when the chat opens
thinkingMessagestringMessage displayed during AI reasoning
titlestringHeader title text
subtitlestringHeader subtitle text
showChatIconbooleanShow/hide the chat icon
showSeparatorbooleanShow/hide the separator between messages
newChatLabelstringLabel for the new chat button
errorMessagestringMessage shown on errors
canRegeneratebooleanEnable message regeneration on failure
regenerateLabelstringLabel for the regenerate button
inputPlaceholderstringPlaceholder text for the input field
maxInputRowsnumberMaximum number of rows for multiline input

​
Runtime behavior

​
Starting a chat

1

User initiates chat

User opens the chat from the UI Flow
2

API call

System calls the start chat API with the configured workflow
3

Session created

API returns a chatSessionId that is persisted for the user
4

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

  1. User types message in input field
  2. Message is sent to the workflow via Chat Input node
  3. Workflow processes the message through AI nodes
  4. 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 ElementStorage LocationDescription
Session IDBrowser storage + DatabaseUnique identifier linking client to server-side session
Message historyFlowX DatabaseComplete record of all messages in the conversation
Session metadataFlowX DatabaseTimestamps, 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:
  1. Loading chat history - When a user returns to an existing chat session
  2. Processing new messages - When a user sends a new message

​
Setting up the FlowX database data source

1

Create the data source

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

Configure the collection

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

Define the data model

Create a data model with the following structure:
FieldTypeDescription
chatSessionIdstringUnique identifier for the chat session
historyarrayList of message objects
history[].actorstringMessage sender (human or agent)
history[].messagestringThe message content

​
Building the workflow

1

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

Add Get chat session node

Add a Database Operation node to retrieve the existing session:
PropertyValue
Operationdb.chat.findOne
DescriptionChat session history
Parameter: chatSessionId${chatSessionId}
Response KeychatSession
3

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
4

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}"
}
5

Add session exists condition

For new messages, add another Condition node to check if the session exists:
input.chatSession.data == null
6

Add Create chat session node

If the session doesn’t exist, add a Database Operation node to create it:
PropertyValue
Operationdb.chat.insertOne
DescriptionCreate chat session
Parameter: chatSessionId${chatSessionId}
Parameter: history[{ "actor": "human", "message": "${humanMessage}" }]
Response KeyresponseKey
7

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);
8

Add Update chat session node

Add a Database Operation node to save the updated history:
PropertyValue
Operationdb.chat.updateOne
DescriptionUpdate chat session
Parameter: chatSessionId${chatSessionId}
Parameter: history${updatedHistory}
Response KeyresponseKey
9

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
  • Components emit and listen for custom events
  • Enables loosely coupled interactions
  • Example: Chat triggers process start event
  • 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:
Track workflow execution with node-by-node timing:
NodeTypical Duration
Start0 ms
Get chat session~133 ms
Check action type~52 ms
Return chat history~60 ms

​
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

ParameterDescriptionRequired
apiUrlYour base FlowX API URL✅
authTokenAuthorization token from auth provider✅
projectIdThe FlowX project ID✅
workspaceIdThe workspace ID✅
sourceSource object with workflow type and ID✅
chatConfigChat configuration object (welcome message, title, etc.)❌
themeIdTheme identifier for styling❌
languageLanguage 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

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

1

Create Knowledge Base

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

Content processing

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

Link to Custom Agent

Connect the Knowledge Base to Custom Agent nodes in your workflow
4

Context retrieval

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

​
Supported file formats

FormatDescription
PDFStandard PDF documents
Markdown.md files with formatted text
WordMicrosoft Word documents (.docx)
ExcelSpreadsheet data (.xlsx)
PowerPointPresentation files (.pptx)
ImagesImage files with text content

​
Configuration options

OptionDescription
Minimum relevanceThreshold for chunk relevance scores (0-1)
Number of responsesLimit how many relevant chunks are returned to the LLM
Content updatesUse 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

Available in v5.5.0 ✓
  • Fill and Overlay display types (Floating, Full Screen)
  • 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

Conversational workflows

Build multi-turn chat experiences with session memory and intent routing
Last modified on March 16, 2026