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.

In this section...