ChatSessionMessage

A single message within a ChatSession. Embedded in ChatSession.messages, not a standalone MongoDB document. Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/ChatSessionMessage.kt TypeScript: hbf-core-api/src/datamodel/chat_session.ts

Fields

Field	Type	Required	Notes
id	String	no	Unique message identifier, set by hbf-bot
responseToId	String	no	ID of the HBFEvent this bot response corresponds to
subscriberHandle	String	no	Handle of the subscriber who sent this message
subscriberName	String	no	Subscriber's display name
subscriberEmail	String	no	Subscriber's email
message	String	no	The message text
tags	Set<String>	no	Message-level tags
intentName	String	no	Triggered intent name
conversationNode	String	no	Triggered conversation node ID
type	ChatSessionMessageType	no	Default: TEXT
category	ChatSessionMessageCategory	no	Default: COMMON
date	Date	no	Timestamp (stored as unix in TS)
isUserInteraction	Boolean	no	Whether message was sent by a user
liveChatEventType	LiveChatEventType	no	Type of live chat event, if applicable
liveChatSender	LiveChatSender	no	END_USER or AGENT, for live chat messages
liveChatConversationId	String	no	Live chat conversation ID
language	String	no	Language used in this message

Enums

ChatSessionMessageType

Value	Description
TEXT	Text message (default)
POSTBACK	Postback from button click
ATTACHMENT	File or media attachment
TRIGGER	System-generated trigger message

ChatSessionMessageCategory

Value	Description
COMMON	Standard message (default)
FEEDBACK	User feedback message
FALLBACK	Fallback/missed question
LIVE_CHAT	Live chat message
BACK	Back navigation message

LiveChatEventType

See chat-session.md.

LiveChatSender

See chat-session.md.

Live Chat Message Patterns

DataCollector in hbf-bot writes messages during live chat with specific patterns. See docs/architecture/flows/live-chat.md for the full data flow.

LIVE_CHAT Category Messages

These represent live chat lifecycle events and message exchanges. Key field patterns:

liveChatEventType	liveChatSender	subscriberHandle	subscriberName	subscriberEmail	isUserInteraction
LIVECHAT_INITIALIZED	END_USER	end-user DirectLine handle	end-user name	-	false
LIVECHAT_REQUESTED	END_USER	end-user DirectLine handle	end-user name	-	true
LIVECHAT_REQUEST_ACCEPTED	AGENT	agent LCM participant ID	agent full name	agent email	true
LIVECHAT_MESSAGE_EXCHANGED	AGENT	agent LCM participant ID	agent full name	agent email	true
LIVECHAT_MESSAGE_EXCHANGED	END_USER	end-user DirectLine handle	end-user name	-	true
LIVECHAT_TERMINATED	AGENT	agent LCM participant ID	agent full name	agent email	true

COMMON Category Messages During Live Chat

Bot-generated messages (system announcements, redirect prompts) use category COMMON even when they occur during a live chat session:

• "Great! I am forwarding your live-chat request." (handover confirmation)
• "Live-chat started" / "Live-chat ended" (system markers)
• Post-redirect messages (e.g., "Do you like chatbots?") after live chat terminates

These have subscriberName: "bot", no liveChatSender, and isUserInteraction: false.

messageCount vs messages.length

messageCount on the ChatSession does not equal messages.length. It counts a subset of messages (typically user-interaction-relevant messages). Expect messageCount < messages.length.

Relationships

• Embedded in: ChatSession.messages (composition)
• References: Subscriber (via subscriberHandle), ConversationNode (via conversationNode)

TypeScript Mapping

hbf-core (Kotlin)	hbf-core-api (TypeScript)	Notes
ChatSessionMessage	ChatSessionMessageDTO	TS uses DTO suffix for read, ChatSessionMessageForm for write
ChatSessionMessageType	ChatSessionMessageType	Aligned
ChatSessionMessageCategory	ChatSessionMessageCategory	Aligned
date (Date)	date (number)	TS uses unix timestamp
tags (Set<String>)	tags (string[] or null)	TS allows null
language (String)	language (LanguageCodes or null)	TS uses enum type

ChatSessionMessageDTO (TypeScript read model)

Field	Type	Notes
id	string or null
responseToId	string or null	Optional
type	ChatSessionMessageType	Required in DTO
category	ChatSessionMessageCategory	Required in DTO
isUserInteraction	boolean or null
subscriberHandle	string or null
subscriberName	string	Required in DTO
subscriberEmail	string or null
message	string
tags	string[] or null
intentName	string or null
conversationNode	string or null
date	number	Unix timestamp
liveChatEventType	LiveChatEventType or null
liveChatSender	LiveChatSender or null
liveChatConversationId	string	Optional
language	LanguageCodes or null

ChatSessionMessageForm (TypeScript write model)

Field	Type	Notes
id	string	Optional
responseToId	string or null	Optional
type	ChatSessionMessageType	Optional
category	ChatSessionMessageCategory	Optional
isUserInteraction	boolean	Optional
subscriberHandle	string	Optional
subscriberName	string	Optional
subscriberEmail	string	Optional
message	string	Required
intentName	string	Optional
conversationNode	string	Optional
date	number	Required
liveChatEventType	LiveChatEventType	Optional
liveChatSender	LiveChatSender	Optional
liveChatConversationId	string	Optional
language	LanguageCodes	Optional