A single conversation session between a subscriber and a bot, including messages, live chat events, and metadata.
Collection: chat-sessions | DB: MongoDB
Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/ChatSession.kt
TypeScript: hbf-core-api/src/datamodel/chat_session.ts
Fields
| Field | Type | Required | Indexed | Notes |
|---|
id | String | yes | PK | MongoDB document ID |
uuid | String | yes | yes (unique) | External session identifier |
duration | Long | yes | | In milliseconds, default 0 |
messages | List<ChatSessionMessage> | yes | | Embedded. See chat-session-message.md |
messageCount | Int | yes | | |
summary | String | no | | AI-generated summary |
sentiment | String | no | | |
resolution | String | no | | |
urgency | String | no | | |
features | HashMap<String, Any> | no | | |
csatSurveys | Set<ChatSessionCSATSurvey> | no | | CSAT survey responses |
status | ChatSessionStatus | yes | | Default: ACTIVE |
subscriberHandle | String | no | | Platform subscriber ID |
language | LanguageCode | no | | |
tags | Set<String> | no | | |
tenant | Tenant | no | | @DBRef lazy |
organizationId | String | yes | | |
lastInteraction | Date | yes | | |
conversationNodes | List<ChatSessionConversationNode> | yes | | Visited nodes |
intents | HashMap<String, Int> | no | | Intent name to hit count |
createdAt | Date | yes | yes | @CreatedDate |
updatedAt | Date | yes | | @LastModifiedDate |
containsUserInteraction | Boolean | yes | | Default: false |
userInteractionCount | Int | yes | | |
liveChats | List<LiveChatSession> | no | | Accepted live chat sessions |
metadata | ChatSessionMetadata | no | | Deployment and subscriber info |
variables | Set<ChatSessionVariableMapping> | no | | Session-level variable values |
Nested Objects
| Field | Type | Notes |
|---|
subscriberName | String | |
subscriberEmail | String | |
subscriberCustomData | BasicDBObject | |
deploymentId | String | |
deploymentName | String | |
platformOrigin | String | |
deploymentPlatform | String | |
isSubscriberNew | Boolean | |
ChatSessionConversationNode
| Field | Type | Notes |
|---|
nodeId | String | Conversation node ID |
appearances | Int | Number of times visited |
ChatSessionVariableMapping
| Field | Type | Notes |
|---|
name | String | Variable name |
value | String | Variable value |
ChatSessionCSATSurvey
| Field | Type | Notes |
|---|
id | String | CSAT node response ID |
name | String | Variable name |
status | String | "PRESENTED" or "ANSWERED" |
sectionsScore | Map<String, Int> | Section name to score |
LiveChatSession
Embedded analytics for a live chat session within a ChatSession. Written by DataCollector in hbf-bot during live chat event processing. See docs/architecture/flows/live-chat.md for the full data flow.
| Field | Type | Notes |
|---|
waitingTime | Long | Seconds waiting for agent (request to accept) |
liveChatEventType | LiveChatEventType | Default: LIVECHAT_REQUESTED. Final state is usually LIVECHAT_TERMINATED |
duration | Long | In seconds, default 0. Full conversation duration (request to terminate) |
responseTime | List<Long> | Per-agent first response times in seconds |
updatedAt | Date | Last update timestamp |
lastEndUserMessageAt | Date | Timestamp of last end-user message |
lastSender | LiveChatSender | END_USER or AGENT |
conversationId | String | LCM conversation ID (matches livechat_conversation.id in LCM MySQL) |
agents | Set<String> | Agent email addresses (e.g., kostas.setzas@helvia.ai) |
tags | List<String> | |
Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/LiveChatSession.kt
Compound Indexes
(organizationId, tenant.$id, status, lastInteraction) - session management queries(organizationId, createdAt, tenant.$id, metadata.deploymentId, duration, liveChats) - analytics(organizationId, tenant.$id, createdAt, metadata.deploymentId, csatSurveys.status) - CSAT analytics(organizationId, tenant.$id, updatedAt) - recent updates(messages._id) - message lookup
Enums
ChatSessionStatus
| Value | Description |
|---|
ACTIVE | Session in progress |
COMPLETED | Session ended |
LiveChatEventType
| Value | Description |
|---|
LIVECHAT_INITIALIZED | Live chat initialized |
LIVECHAT_REQUESTED | End-user requested live chat |
LIVECHAT_REQUEST_CLOSED | Request closed |
LIVECHAT_REQUEST_ACCEPTED | Agent accepted request |
LIVECHAT_REQUEST_MISSED | Request missed by agents |
LIVECHAT_TERMINATION_REQUESTED | Termination requested |
LIVECHAT_TERMINATED | Live chat terminated |
LIVECHAT_ABANDONED | Live chat abandoned |
LIVECHAT_TRANSFERRED | Transferred to another agent |
LIVECHAT_MESSAGE_EXCHANGED | Message exchanged |
LIVECHAT_MESSAGE_TYPING | Typing indicator |
LIVECHAT_IS_DISABLED | Live chat is disabled |
LIVECHAT_REQUEST_EXISTS | Duplicate request |
LIVECHAT_OUT_OF_BUSINESS_HOURS | Outside business hours |
LIVECHAT_IS_IN_PROGRESS | Already in progress |
LIVECHAT_GENERIC_ERROR | Generic error |
SOURCE_REQUEST_NEW_HANDOVER | ITC: new handover requested (old: LIVECHAT_REQUESTED_OLD) |
SOURCE_PRE_REQUEST_NEW_HANDOVER | ITC: pre-request handover (old: LIVECHAT_INITIALIZED_OLD) |
LiveChatSender
| Value | Description |
|---|
END_USER | Message from end user |
AGENT | Message from live agent |
Relationships
- Belongs to: Tenant (via @DBRef), Organization (via organizationId)
- Contains: ChatSessionMessage (composition), LiveChatSession (composition)
- Referenced by: Survey (via @DBRef)
TypeScript Mapping
| hbf-core (Kotlin) | hbf-core-api (TypeScript) | Notes |
|---|
| ChatSession | ChatSessionDTO | TS uses DTO suffix |
| ChatSessionMessage | ChatSessionMessageDTO | See chat-session-message.md |
| LiveChatSession | LiveChatSessionDto | Aligned. TS has tags omitted |
| ChatSessionCSATSurvey | ChatSessionCSATSurvey | Aligned |
| ChatSessionConversationNode | ChatSessionConversationNode | Aligned |
| ChatSessionVariableMapping | ChatSessionVariableMapping | Aligned. TS value is optional |
| ChatSessionMetadata | object | TS types metadata as generic `object |
| ChatSessionStatus | ChatSessionStatuses | Different naming |
| LiveChatEventType | LiveChatEventType | TS adds LIVECHAT_CALL_REQUESTED |
| LiveChatSender | LiveChatSender | Aligned |