View Source

Display a chat conversation thread between an end-user and an AI model.

Reference → Controls → Interaction → ChatSession

The ChatSession control belongs to the Interaction category and runs on the Portable rendering target (WPF rich client and HTML5/WASM). Place it on a Display from the Components Panel and configure the properties listed below.

ChatSession renders a vertical, auto-scrolling list of message bubbles, visually distinguishing user messages from AI messages. It is the standard FrameworX surface for an operator chat or LLM-assistant pane inside a SCADA/HMI Display.

Overview

ChatSession is the FrameworX Display control for conversational AI inside a process-control or operator console. It renders a scrolling thread of message bubbles bound to an items source — typically the platform-managed per-Display-panel transcript from the ChatRequest action, a Dataset table, a List-typed Tag, or a Script-returned collection — where each item carries a role (user vs AI) and a body text. The control inspects each item's role value, compares it against UserRoleValue and AIRoleValue, and styles the bubble accordingly (alignment, colors, corner shaping).

Primary pattern — ChatRequest with auto-managed transcript

In FrameworX 10.1.5, the standard operator chat panel pairs ChatSession with the ChatRequest Display Action. No scripting is required:

A TextBox for the user prompt and a Button whose Action is set to ChatRequest (Query tag, Return tag configured in the Action editor).
A ChatSession control bound to the same Display panel. The platform automatically maintains the per-Display-panel transcript — each turn the operator sends is appended to the conversation history server-side; the AI reply is appended after the model responds. The customer does not need to write Script code to manage this collection.

The per-Display-panel transcript is keyed internally by the client connection and resets transparently on operator login change (shift change). It can be disabled solution-wide via the EnableChatHistory bit on SolutionSettings.ModelOptions. See ChatRequest Action Reference for full transcript semantics.

Alternative pattern — Script-managed collection

When the conversation source is not the platform-managed transcript — for example, a persisted chat log driven by a Dataset, or a custom in-memory collection a Script assembles — a typical assistant pane wires three pieces:

A TextBox for the user prompt and a Button whose Action invokes a Script.
A Server-side Script that appends the user message to the conversation collection, then calls an LLM via the FrameworX HTTP CHAT verb (routed through the in-product ChatSession orchestrator and the ChatRequest API). On response, the Script appends the AI reply to the same collection.
A ChatSession control bound to that collection. The control re-renders on any collection change, and — when AutoScrollToBottom is true — brings the newest message into view automatically.

Because the control runs on the Portable target, the same Display works in the WPF Rich Client and in the HTML5/WASM Smart Client without modification.

Bindings

ChatSession uses the standard FrameworX itemized-source pattern. The conversation collection is provided through three coordinated properties:

Property	Use in an AI chat pattern
`ItemsSourceType`	Selects the kind of source. Use `DataTable` when conversations are persisted (Dataset Query or Table holding one row per message); use `ArrayTag` when the conversation lives in memory as a List-typed Tag; use `Text` for a static seeded thread.
`ItemsSourceLink`	The actual source reference, interpreted per `ItemsSourceType`. For persisted chats: `@Dataset.Query.ConversationByUser` (or similar). For in-memory chats: `@Tag.ChatThread` where `ChatThread` is a List Tag whose item members include a role field and a body field. The control re-renders on collection change.
`ItemsSourceOption`	Legacy source-selection mode kept for compatibility; new Displays should prefer `ItemsSourceType` + `ItemsSourceLink`.

Whichever source is chosen, each item must expose a role value comparable to UserRoleValue / AIRoleValue and a body text. For Dataset sources, name the role column and body column to match what the Script appends; for List-Tag sources, define a UserType with at least Role and Body members.

Properties

Property set auto-extracted from ControlSchemas.json (build fx-10.1.5.2000, schema 1.0, generated 2026-05-17T21:29:29.5050227Z).

Property	Type	Default	Description
`Left`	`Double`	0	X position from left edge (unit: pixels)
`Top`	`Double`	0	Y position from top edge (unit: pixels)
`Width`	`Double`	100	Element width (unit: pixels)
`Height`	`Double`	100	Element height (unit: pixels)
`AutoScrollToBottom`	`Boolean`	(none)	(no description in schema)
`UserRoleValue`	`String`	(none)	(no description in schema)
`AIRoleValue`	`String`	(none)	(no description in schema)
`BubbleCornerRadius`	`Double`	(none)	(no description in schema)
`DesignQuantity`	`Integer`	(none)	(no description in schema)
`PreviewQuantity`	`Integer`	(none)	(no description in schema)
`DesignElements`	`String`	(none)	(no description in schema)
`PreviewElements`	`String`	(none)	(no description in schema)
`PreviewMargin`	`String`	(none)	(no description in schema)
`DesignSingleType`	`Boolean`	(none)	(no description in schema)
`PreviewSingleType`	`Boolean`	(none)	(no description in schema)
`PreviewSettings`	`String`	(none)	(no description in schema)
`DesignWidth`	`Double`	100	(no description in schema)
`PreviewWidth`	`Double`	(none)	(no description in schema)
`DesignHeight`	`Double`	100	(no description in schema)
`PreviewHeight`	`Double`	(none)	(no description in schema)
`DesignMargin`	`String`	5	(no description in schema)
`DesignSettings`	`String`	(none)	(no description in schema)
`MaxItemsLink`	`String`	(none)	(no description in schema)
`ItemsSourceOption`	`Enum`	0	Data source type: Designer (static list), ArrayTag (tag array), DataTable
`ItemsSourceType`	`Enum`	(none)	Source kind: Text (static list via ItemsList), ArrayTag (array tag values), DataTable (Dataset Query or Table — FK pattern). For FK dropdowns use DataTable + ItemsSourceLink='@Dataset.Query.X' + DisplayMemberPath + SelectedValuePath.
`ItemsSourceLink`	`String`	(none)	Source for populating list items. Interpretation depends on ItemsSourceType: Text → @Tag.OptionsList (array or CSV tag) ArrayTag → @Tag.ArrayOfStrings DataTable → @Dataset.Query.NameOfQuery (RECOMMENDED for FK dropdowns) In DataTable mode the ComboBox auto-fires the backing query at display-open — no script Select() needed.
`ReloadItemsLink`	`String`	(none)	Tag that triggers list refresh when its value changes
`ContainerPanel`	`Enum`	0	(no description in schema)
`Background`	`Color`	(none)	Background color (#AARRGGBB). Themed by default — OMIT to use theme.
`Foreground`	`Color`	(none)	Text/foreground color (#AARRGGBB). Themed by default — OMIT to use theme.
`BorderBrush`	`Color`	(none)	Border color (#AARRGGBB).
`BorderThickness`	`String`	(none)	Border thickness (single value or 'left,top,right,bottom').

ChatSession-specific properties

The auto-generated table above ships with empty descriptions for several ChatSession-specific properties. Until the next schema regeneration carries the descriptions through, use the editorial notes below.

Property	Description
`AutoScrollToBottom`	When `true`, the viewport scrolls to the newest message as soon as the bound collection grows. Recommended for live operator chat panes so a new AI reply is visible without user interaction. Set to `false` when reviewing historical transcripts where the user expects the scroll position to be preserved.
`UserRoleValue`	The string the control treats as the user role marker. Each item in the bound collection whose role field equals this value is rendered as a user bubble (right-aligned by default). May be a literal (e.g. `user`) or a tag-bound expression. Must match exactly what the Script writes when appending user messages.
`AIRoleValue`	The string the control treats as the AI role marker. Items whose role field equals this value render as AI bubbles (left-aligned by default). May be a literal (e.g. `assistant`) or a tag-bound expression. Items whose role matches neither marker fall back to the default bubble style.
`BubbleCornerRadius`	Corner rounding of each message bubble, in pixels. `0` renders square bubbles; higher values produce a more conversational, mobile-style appearance. Applies uniformly to user and AI bubbles.

Additional Properties

The properties below also ship with empty descriptions in the auto-generated table. They configure Designer-time and Preview-mode rendering of sample items inside the ChatSession surface. Behaviors are conservative best-effort from the schema shape; consult ControlSchemas.json for the current default value.

Property	Description
`DesignQuantity`	Number of sample items rendered in the Designer canvas when no live source is bound. Used so the control occupies meaningful space while the Display is being authored.
`PreviewQuantity`	Number of sample items rendered in Preview mode. Lets the author validate scrolling and bubble layout against a representative item count before going live.
`DesignElements`	Comma- or newline-separated sample items rendered inside the control at design time. Each entry produces one preview bubble. Use to visualize the bubble styling without binding a source.
`PreviewElements`	Same shape as `DesignElements` but rendered while the Display is in Preview mode. Lets the author drive the live rendering path with a known sample set.
`PreviewMargin`	Outer spacing around preview items, in pixels. Single value applies uniformly; `left,top,right,bottom` applies per side. Controls how preview items pack inside the ChatSession frame.
`DesignSingleType`	When `true`, restricts the Designer preview to a single role — user OR AI — so the author can validate one bubble style in isolation. When `false`, design preview alternates roles.
`PreviewSingleType`	Same as `DesignSingleType` but applied in Preview mode. Useful when the live source is mocked with a single-role sample.
`PreviewSettings`	Serialized render settings applied to Preview-mode items (typography, color overrides, spacing). Edited through the Designer property editor rather than by hand; consult `ControlSchemas.json` for the current default value.
`PreviewWidth`	Width of the preview frame within the control, in pixels. Controls how wide each preview bubble may stretch before wrapping. Defaults to the auto-generated design-mode width when unset.
`PreviewHeight`	Height of the preview frame within the control, in pixels. Combined with `PreviewQuantity` determines whether preview content scrolls.
`DesignSettings`	Serialized render settings applied to Designer-canvas items (counterpart to `PreviewSettings`). Controls typography, colors, and spacing while the Display is being authored. Edited through the Designer property editor; consult `ControlSchemas.json` for the current default value.
`MaxItemsLink`	Tag expression that caps the maximum number of items the control will render from the bound source. When unset, the full bound collection is rendered. Use for live operator chat panes where the visible history must be bounded to keep the bubble list responsive.

Related actions

ChatSession is a rendering control. The Display Actions listed below operate on the server-side transcript that ChatSession displays. Attach them to Buttons on the same Display panel to give operators full control of the conversation lifecycle.

Action	What it does
ChatRequest Action Reference	Sends the operator’s query to the LLM, manages the per-panel transcript across turns, and dispatches platform tools the model may request. The primary action for an operator chat panel.
ChatClear Action Reference	Wipes the transcript for the addressed chat session immediately, without calling the LLM. Use for “Start new conversation” buttons and shift-handover resets.
ChatCompress Action Reference	Summarises the current transcript via one LLM call and atomically replaces it with the summary. Preserves semantic continuity while reducing token cost on long conversations.