Chat component

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

Flexible display modes

Inline, Overlay, FullScreen, and Floating modes with per-mode theming for Web, Android, and iOS

Display modes

Updated in FlowX.AI 5.6.0The Chat component now supports four distinct display modes, replacing the previous Fill/Overlay model. Mobile chat support was also added in this release.

When adding a Chat component, you choose a display mode that determines how the chat renders and behaves at runtime.

Display mode	Description	Placement
Inline	Renders in place within the page layout (default)	Child of any container or card
Overlay	Positioned overlay panel with minimize and expand controls	Child of Page or Root Zone
FullScreen	Takes over the full viewport	Child of Page or Root Zone
Floating	Floating panel triggered by a FAB (Floating Action Button)	Child of Page or Root Zone

You can change the display mode after creation if needed.

Mode details

Inline
Overlay
FullScreen
Floating

Renders within the parent component, filling the available space. This is the default mode.

Can be a child of any container or card
Embeds directly into the page layout
Best for dedicated chat pages or inline chat experiences
Width and height follow the parent container; supports Fill or Fixed sizing

Renders as a floating panel anchored to a corner of the screen. Triggered by a Floating Action Button (FAB).

Must be a child of Page or Root Zone
FAB defaults to bottom-right position (right: 24px, bottom: 24px)
FAB dimensions: 56 × 56px (configurable)
Chat panel defaults: 420px wide, 640px tall
Best for persistent, always-accessible chat without interrupting main content

Sizing defaults

Display mode	Default width	Default height	Notes
Inline	Fill (parent)	Fill (parent)	Supports Fill or Fixed sizing
Overlay	Configurable	Configurable	Positioned over content
FullScreen	Full viewport	Full viewport	No sizing controls
Floating	`420px` (fixed)	`640px` (fixed)	FAB at `right: 24px`, `bottom: 24px`

Theming per display mode

Theme values can be set independently for each display mode and per platform (Web, Android, iOS) through Design Assets → Themes → Components → Chat.

Platform	Configurable modes
Web	Inline, Floating, FullScreen
Android	Inline, Floating, FullScreen
iOS	Inline, Floating, FullScreen

Each mode supports independent configuration for padding, margin, and other layout tokens.

Chat header button and URL synchronization

The chat header includes a state-aware button that adapts based on the current display mode (for example, toggling between fullscreen and overlay views). Chat session state is also synchronized to the browser URL via popstate, so navigating back or refreshing the page restores the correct session context.

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

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:

Subcomponent	Description
Header	Configurable header with avatar, title, subtitle, new chat button, fullscreen toggle, and dock/collapse controls
Messages	Message display with sender/receiver differentiation, markdown rendering, and avatar support
Chat History	Conversation history list showing past chat sessions grouped by time, with the ability to resume previous conversations
Suggested Prompts	Pre-configured prompt suggestions displayed before the user types, allowing quick-start interactions
Reasoning	Displays AI reasoning steps (thinking indicators) during response generation
Input	Message 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.

Property	Description
reasoning	Toggle to show/hide reasoning steps in the chat
thinkingMessage	Custom 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:

Property	Description
errorMessage	Custom error message to display on failure
canRegenerate	Enable the regenerate button on failed messages
regenerateLabel	Custom label for the regenerate button

Chat History

Available starting with FlowX.AI 5.6.0The Chat History subcomponent lets users browse and resume past conversations.

Chat History displays a list of conversations started by the current user, grouped by time period: Today, Yesterday, Previous 7 Days, Previous 30 Days, and Older.

Chat History panel showing past conversations grouped by time

Behavior

The chat history button is always visible in the chat header
When opened, the list shows each conversation with its title and timestamp (displayed in a tooltip)
Available actions: New chat, Expand/Minimize, Dock (hide chat)
Opening a conversation from the list resumes the session:
- Messages are prefilled with the last exchanged messages
- Scrolling up loads older replies
- New messages continue on the same session ID
Conversations are per-user — attempting to access another user’s history shows an access denied error and redirects to a new chat session

Theming

Chat History adds three new themed elements configurable per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through Design Assets → Themes → Components → Chat:

Theme element	Description
Chat History	Container for the conversation list (padding, empty state font/color, gap)
Chat History Section	Time-group headers like “Today” or “Previous 7 Days” (title font/color, gap)
Chat History Item	Individual conversation entry with hover state (padding, font, border radius, background color)

Two new system icons are added: sys_ChatHistory and sys_ChatBack.

Localization

Chat History uses system substitution tags for all labels. Override these in CMS → Substitution Tags to customize or localize:

Substitution tag	Default (EN)
`sys_chat_tooltip_chat_history`	Chat History
`sys_chat_tooltip_new_chat`	New chat
`sys_chat_tooltip_expand`	Expand
`sys_chat_tooltip_minimize`	Exit full screen
`sys_chat_tooltip_dock`	Hide chat
`sys_chat_tooltip_back`	Back
`sys_chat_time_group_today`	Today
`sys_chat_time_group_yesterday`	Yesterday
`sys_chat_time_group_previous_7_days`	Previous 7 Days
`sys_chat_time_group_previous_30_days`	Previous 30 Days
`sys_chat_time_group_older`	Older
`sys_chat_conversations_empty_state`	No Conversations yet
`sys_chat_forbidden`	Access denied. This chat history belongs to another user.

Markdown rendering in messages

Available starting with FlowX.AI 5.6.0Chat messages now render Markdown formatting in AI-generated responses.

Agent (receiver) messages support Markdown formatting, allowing AI-generated responses to include structured content. The renderer automatically converts Markdown syntax to styled HTML. Supported syntax:

Syntax	Renders as
`bold`	Bold text
`italic`	Italic text
`# Heading` through `###### Heading`	Heading levels 1–6
`inline code`	Inline code
``` code block ```	Fenced code block
`- item` or `1. item`	Unordered and ordered lists
`[text](url)`	Hyperlink (opens in a new tab)
Single newline	Line break (`<br/>`)

When building AI agent prompts, you can instruct the agent to format responses using Markdown — the chat component renders the output automatically.

Suggested Prompts

Available starting with FlowX.AI 5.6.0The Suggested Prompts subcomponent is a child of CHAT_MESSAGES, alongside Agent Message, User Message, and Error Message.

The Suggested Prompts subcomponent displays a set of pre-configured prompt suggestions to the user before they begin typing. When a suggestion is clicked, its text is sent as the user’s input, starting the conversation immediately.

Suggested Prompts displayed in chat empty state

Props

Property	Type	Default	Description
`title`	string	`"Suggested Prompts"`	Section heading displayed above the prompt list
`prompts`	string[]	—	Array of prompt strings to display as suggestions

Behavior

The subcomponent only renders when at least one prompt is provided in the prompts array. If the array is empty or not set, the section is hidden entirely.
Clicking a suggestion sends that prompt text as the user’s input, triggering the chat workflow as if the user typed and submitted the message.
Long prompt strings that exceed the display area are truncated and shown in full via a tooltip on hover.

Theming

Full theming support is available in both Angular and React SDKs. Styles can be configured per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through Theme Admin (Design Assets → Themes → Components → Chat → Suggested Prompts).

Use suggested prompts to guide users toward the most common questions or actions in your chat experience. Keep individual prompts short and action-oriented so they remain readable without truncation.

Chat configuration

The chatConfig object controls the behavior and appearance of the chat:

Property	Type	Description
`welcomeMessage`	string	Initial message shown when the chat opens
`thinkingMessage`	string	Message displayed during AI reasoning
`title`	string	Header title text
`subtitle`	string	Header subtitle text
`showChatIcon`	boolean	Show/hide the chat icon
`showSeparator`	boolean	Show/hide the separator between messages
`newChatLabel`	string	Label for the new chat button
`errorMessage`	string	Message shown on errors
`canRegenerate`	boolean	Enable message regeneration on failure
`regenerateLabel`	string	Label for the regenerate button
`inputPlaceholder`	string	Placeholder text for the input field
`maxInputRows`	number	Maximum number of rows for multiline input
`historyTitle`	string	Title text displayed on the chat history 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.

Conversation history API

FlowX provides REST API endpoints for retrieving conversation history programmatically. These are useful for building custom dashboards, analytics, or integrating conversation data into external systems.

List conversations

Retrieve all conversations for the current authenticated user within a workspace and app.

GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations

Path parameters:

Parameter	Type	Description
`workspaceId`	UUID	The workspace identifier
`appId`	UUID	The app identifier

Query parameters (optional):

Parameter	Type	Description
`startDate`	ISO 8601 timestamp	Filter conversations created after this date
`endDate`	ISO 8601 timestamp	Filter conversations created before this date
`businessCaseId`	UUID	Filter by business case identifier

Response:

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "state": "ACTIVE",
      "createdAt": "2026-03-10T14:30:00Z",
      "summary": "Customer asked about account verification process",
      "messageCount": 12
    }
  ],
  "total": 1
}

Fetch a single conversation

Retrieve a single conversation with its full message history.

GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations/{conversationId}

Path parameters:

Parameter	Type	Description
`workspaceId`	UUID	The workspace identifier
`appId`	UUID	The app identifier
`conversationId`	UUID	The conversation (chat session) identifier

Query parameters (optional):

Parameter	Type	Description
`page`	integer	Page number for message pagination
`size`	integer	Number of messages per page

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "ACTIVE",
  "summary": "Customer asked about account verification process",
  "createdAt": "2026-03-10T14:30:00Z",
  "userEmail": "user@example.com",
  "messages": [
    {
      "actor": "human",
      "message": "How do I verify my account?",
      "timestamp": "2026-03-10T14:30:05Z",
      "messageId": "msg-001"
    },
    {
      "actor": "agent",
      "message": "To verify your account, navigate to **Settings** → **Verification**...",
      "timestamp": "2026-03-10T14:30:08Z",
      "messageId": "msg-002"
    }
  ]
}

Error responses:

Status	Description
`404`	Conversation not found
`403`	User does not have access to this conversation

These endpoints return conversations owned by the authenticated user only. The workspace must belong to the user’s organization.

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.5.0 ✓ · Display modes expanded in v5.6.0

All four display modes: Inline, Overlay, FullScreen, Floating
Complete feature set including Suggested Prompts and Markdown rendering
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

Config-time agents

Agent Builder

Using agents

Tutorials

AI Patterns

​Key features

Real-time messaging

AI agent integration

Session management

Message history

Knowledge Base integration

Reasoning transparency

Flexible display modes

​Display modes

​Mode details

​Sizing defaults

​Theming per display mode

​Chat header button and URL synchronization

​Global component

​Sizing

​Subcomponents

​Reasoning display

​Error handling and regeneration

​Chat History

​Behavior

​Theming

​Localization

​Markdown rendering in messages

​Suggested Prompts

​Props

​Behavior

​Theming

​Chat configuration

​Runtime behavior

​Starting a chat

​Message exchange

​Session management

Session persistence

Message history retrieval

​Data storage

​Conversation history API

​List conversations

​Fetch a single conversation

​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

Display modes

Mode details

Sizing defaults

Theming per display mode

Chat header button and URL synchronization

Global component

Sizing

Subcomponents

Reasoning display

Error handling and regeneration

Chat History

Behavior

Theming

Localization

Markdown rendering in messages

Suggested Prompts

Props

Behavior

Theming

Chat configuration

Runtime behavior

Starting a chat

Message exchange

Session management

Data storage

Conversation history API

List conversations

Fetch a single conversation

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