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 — pair it with a Dataset, an in-memory List Tag, or a Script-returned collection to drive the conversation, and with the ChatRequest Script API (HTTP verb CHAT) to dispatch prompts to a backing language model.

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

A typical assistant pane in an operator Display 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.

In this section...