Flow: Live Chat Handover

End-to-end sequence for handing a conversation from bot to human agent and back. Services: hbf-bot, hbf-lcg, hbf-lcm, hbf-session-manager, hbf-event-publisher, hbf-console

Sequence Diagram

Step-by-Step

Handover trigger (hbf-bot -> hbf-lcg -> hbf-lcm): The bot workflow encounters a handover node and sends POST /requests to hbf-lcg (via LiveChatGatewayClient). hbf-lcg routes the request to hbf-lcm via POST /livechat-requests with the subscriber handle, tenant, and conversation context.
Agent routing (hbf-lcm -> hbf-core): hbf-lcm validates the tenant configuration and checks agent availability via hbf-core. It determines which agent or group should receive the request based on routing rules.
Agent notification (hbf-lcm -> hbf-console): hbf-lcm emits a Socket.IO event (REQUEST_CREATE) to connected console sessions. The request appears in the agent's live chat queue.
Agent accepts (hbf-console -> hbf-lcm -> hbf-bot): When the agent accepts the request, hbf-lcm emits CONVERSATION_JOIN and sends a callback to hbf-bot with type: "CONVERSATION_BEGIN", signaling that the bot should route subsequent user messages through live chat.
Message relay (hbf-console <-> hbf-lcm <-> hbf-lcg <-> hbf-bot): Agent messages flow from the console via Socket.IO to hbf-lcm, then to hbf-lcg, which sends HTTP callbacks to hbf-bot's /livechat-events endpoint with EventOrigin.LIVECHAT. hbf-bot processes the event (state loading, forwarding check), creates an ITC (Internal To Client) event with EventOrigin.ITC, and re-enters the pipeline. DataCollector runs only on the ITC pass, writing the chatSessionMessage to MongoDB. The message is then dispatched to the end user via DirectLine. User replies follow the reverse path.
Typing indicators: hbf-lcm relays typing events through hbf-lcg to hbf-bot via type: "CONVERSATION_TYPING" callbacks.
Conversation end (hbf-lcm -> hbf-lcg -> hbf-bot, hbf-event-publisher): When the agent closes the conversation (or the bot ends it), hbf-lcm sends a CONVERSATION_END event through hbf-lcg to hbf-bot. The bot processes the LIVECHAT_TERMINATED event, creates an ITC event, and DataCollector records it. The bot then executes the post-termination workflow (e.g., redirect to a "Do you like chatbots?" prompt). hbf-lcm also triggers a livechat-conversation-finished flow event via hbf-event-publisher.
Missed request (fallback): If no agent is available within the timeout, hbf-lcm sends REQUEST_MISSED to hbf-bot and triggers a livechat-request-missed flow event. The bot can then execute a fallback workflow (e.g., collect contact info).
Transfer: An agent can transfer the conversation to another agent or group. hbf-lcm notifies hbf-bot with type: "TRANSFER_REQUEST".
Session completion (hbf-session-manager): hbf-session-manager detects expired or ended sessions, marks them complete in hbf-core, triggers chat-session-completed via hbf-event-publisher, requests NLP summarization via POST /sessions/:id/analyze, and delivers the completed session payload to any registered customer webhooks.

Event Origins and DataCollector Analytics

Live chat events arrive at hbf-bot with two different EventOrigin values, and DataCollector treats them differently:

Event Origins

Origin	Source	Example Events
`LIVECHAT`	Raw events from hbf-lcg (agent messages, typing, accept, terminate)	Agent sends message, agent accepts request, agent terminates
`ITC` (Internal To Client)	hbf-bot re-emits LIVECHAT events internally for end-user delivery	Same events, re-processed through the bot pipeline to reach the end user via DirectLine

DataCollector Gate

DataCollector._isEnabled() returns false for EventOrigin.LIVECHAT. This means raw LCG events do NOT produce analytics. Only the ITC-reprocessed versions create chatSessionMessage records in MongoDB.

This is intentional: the LIVECHAT event handles the bot-side processing (state loading, forwarding), while the ITC event handles the client-facing delivery and analytics recording.

Message Flow with Analytics

Agent sends message in console
  -> hbf-lcm -> hbf-lcg -> hbf-bot (livechat-events, origin=LIVECHAT)
  -> LiveChatGatewayChannel converts to HBFEvent
  -> Lifecycle pipeline processes (DataCollector SKIPPED: _isEnabled()=false for LIVECHAT)
  -> ITC event created and re-enters pipeline (origin=ITC)
  -> DataCollector runs: creates chatSessionMessage in MongoDB chat-sessions.messages[]
  -> Message dispatched to end user via DirectLine

Chat Session Message Categories

DataCollector writes messages with these categories during live chat:

Category	When	Fields Set
`LIVE_CHAT`	Live chat trigger/event messages (accept, terminate, message exchange)	`liveChatEventType`, `liveChatSender`, `liveChatConversationId`, `subscriberHandle`, `subscriberName`, `subscriberEmail` (for AGENT sender)
`COMMON`	Bot responses (system messages like "Live-chat started", redirect messages like "Do you like chatbots?", post-redirect flow)	`subscriberName: "bot"`, `responseToId`

Sender-Based Field Resolution

For LIVE_CHAT category messages, DataCollector resolves identity fields based on liveChatSender:

Field	END_USER	AGENT
`subscriberHandle`	End user's DirectLine handle	Agent's LCM participant ID (e.g., `6066f617...`)
`subscriberName`	End user's display name (e.g., "User")	Agent's full name (e.g., "Kostas Setzas")
`subscriberEmail`	Not set	Agent's email (e.g., `kostas.setzas@helvia.ai`)

LiveChat Aggregate (`liveChats[]`)

Each accepted live chat session produces a LiveChatSession entry in chat-sessions.liveChats[]:

Field	Unit	Description
`waitingTime`	seconds	Time between handover request and agent accept
`duration`	seconds	Total conversation duration (request to terminate)
`responseTime`	seconds[]	Per-agent first response time
`agents`	string[]	Agent email addresses
`conversationId`	string	LCM conversation ID
`liveChatEventType`	enum	Final state (usually `LIVECHAT_TERMINATED`)
`lastEndUserMessageAt`	Date	Timestamp of last end-user message
`lastSender`	enum	`END_USER` or `AGENT`

LCM MySQL Messages (parallel storage)

hbf-lcm stores its own copy of live chat messages in MySQL livechat_message table, joined with livechat_participant for sender info. This is separate from hbf-bot's MongoDB storage and serves the console's live chat UI.

Contracts

hbf-bot -> hbf-lcg (POST /requests) -> hbf-lcm (POST /livechat-requests):

Request: {
  "subscriberHandle": "string",
  "tenantId": "string",
  "sessionId": "string",
  "message": "string",
  "context": {}
}

hbf-lcm -> hbf-bot (callback, 6 event types):

POST HBF_BOT_EVENT_URL
{
  "type": "CONVERSATION_BEGIN | MESSAGE | CONVERSATION_END | CONVERSATION_TYPING | TRANSFER_REQUEST | REQUEST_MISSED",
  "data": {
    "subscriberHandle": "string",
    "tenantId": "string",
    "sessionId": "string",
    "message": "string",
    "agent": { "id": "string", "name": "string" }
  }
}

hbf-lcm -> hbf-console (Socket.IO events):

event with types: REQUEST_CREATE, CONVERSATION_JOIN, CONVERSATION_LEAVE, CONVERSATION_END
message with chat message payload

hbf-lcm -> hbf-event-publisher (POST /connectors/flows:trigger):

{
  "event": "livechat-request-missed | livechat-conversation-finished",
  "data": { "tenantId": "string", "sessionId": "string", "subscriberHandle": "string" }
}

hbf-session-manager -> hbf-event-publisher (POST /connectors/flows:trigger):

{
  "event": "chat-session-completed",
  "data": { "tenantId": "string", "sessionId": "string" }
}

hbf-session-manager -> hbf-nlp (POST /sessions/:id/analyze): Triggers NLP summarization of the completed session transcript.

hbf-session-manager -> Customer webhooks (POST <registered URL>): Delivers the completed session payload (session metadata, transcript, analytics) to customer-registered webhook endpoints.

Sequence Diagram​

Step-by-Step​

Event Origins and DataCollector Analytics​

Event Origins​

DataCollector Gate​

Message Flow with Analytics​

Chat Session Message Categories​

Sender-Based Field Resolution​

LiveChat Aggregate (liveChats[])​

LCM MySQL Messages (parallel storage)​

Contracts​