Skip to main content

AI Brief: hbf-lcm

Live Chat Manager (LCM) is a NestJS microservice that routes messages between end-users (via hbf-bot) and human support agents (via hbf-console) over Socket.IO. It manages conversation lifecycle, agent assignment, business hours, and idle monitoring in MySQL, with optional Redis for multi-instance coordination.

What This Repo Does​

hbf-lcm receives livechat requests and messages from hbf-bot over REST and persists them to MySQL. It broadcasts those messages to the correct agent rooms on Socket.IO. Agents connect from hbf-console via WebSocket, authenticate with JWT, and interact with conversations through both socket events and REST endpoints. The service also enforces business hours, monitors idle/expired requests and conversations on a schedule, and supports MS Teams and Twilio video integrations.

Tech Stack​

  • Language: TypeScript / Node.js
  • Framework: NestJS 11
  • Database: MySQL / MariaDB via TypeORM 0.3
  • Real-time: Socket.IO (@nestjs/platform-socket.io, @nestjs/websockets)
  • Cache: in-memory or Redis (@keyv/redis, @nestjs/cache-manager)
  • Socket clustering: @socket.io/redis-adapter
  • Scheduling: @nestjs/schedule (cron + interval)
  • Events: @nestjs/event-emitter
  • HTTP client: got 11
  • Video: twilio 5
  • Logging: nestjs-pino + @elastic/ecs-pino-format
  • APM: elastic-apm-node

Entry Points​

  • Main: src/main.ts
  • App module: src/app.module.ts
  • Config: .env / .env.local

Key Directories​

DirectoryPurpose
src/services/sockets/Socket.IO gateway — agent connections, room management, message/event relay
src/services/livechat/core/LivechatCoreService — dispatches to PUBLIC or SEMI-PRIVATE service cluster
src/services/livechat/core/public/PUBLIC mode: any agent sees all conversations
src/services/livechat/core/semi-private/SEMI-PRIVATE mode: agents see only their assigned conversations
src/services/livechat/conversations/Conversation CRUD and state management
src/services/livechat/requests/Livechat request (queue entry) management
src/services/livechat/settings/Per-organization livechat settings, incl. business hours
src/services/monitor/Scheduled monitor: expires idle requests and conversations
src/services/clients/HTTP clients: hbf-core, hbf-bot, MS Teams, hbf-event-publisher
src/services/relay/REST proxy for hbf-bot to reach hbf-core (contacts, tags, messages)
src/services/integrations/Callback and notification handlers for external platforms (MS Teams)
src/services/predefined/Predefined responses and actions
src/services/twilio/Twilio video call token generation
src/services/storage/S3-compatible file storage for attachments
src/migrations/TypeORM migration files
src/entities/TypeORM entities: LivechatConversation, LivechatRequest, LivechatMessage, etc.

API Surface​

Key controllers:

  • GET / — name + version
  • GET /health — health check (no auth)
  • GET /config — extended config info (LCM token required)
  • POST /livechat-requests — create a livechat request (hbf-bot, LCM token)
  • GET /users/:userId/livechat-requests — get requests by end-user (LCM token)
  • GET /organizations/:orgId/livechat-requests — get org requests (LCM token)
  • GET /agent/organizations/:orgId/livechat-requests — agent view of requests (HBF token)
  • POST /organizations/:orgId/livechat-messages — post message from bot (LCM token)
  • GET /agent/organizations/:orgId/livechat-conversations — list conversations (HBF token)
  • GET /organizations/:orgId/livechat-conversations/:id — single conversation (HBF token)
  • GET /organizations/:orgId/livechat-messages — list messages (HBF token, supports CSV/PDF)
  • POST /livechat-attachments — upload attachment (HBF token)
  • GET/PUT /organizations/:orgId/livechat-settings — livechat settings (HBF token)
  • DELETE /organizations/:orgId/data-retention — purge data before date (LCM token)
  • GET, POST, PATCH, DELETE /organizations/:organizationId/user-groups/:userGroupId/business-hours — business hours config (HBF token)
  • GET /organizations/:orgId/tenants/:tenantId/chat-sessions/:id/messages — relay to hbf-core (HBF token)
  • Various notes, predefined response, and MS Teams callback endpoints

WebSocket (Socket.IO):

  • connection — agent authenticates with JWT; joins personal room (orgId:userId), org room, and group rooms
  • message (inbound) — agent sends a chat message
  • event (inbound) — agent sends an event (accept, transfer, end conversation, etc.)
  • message (outbound) — server pushes a message to an agent room
  • event (outbound) — server pushes an event (e.g., AUTHORIZATION_GRANTED, NOTIFICATION, ERROR)

External Dependencies​

  • hbf-core: user auth (/users/me), organization/tenant data, tags, contacts, chat session messages
  • hbf-bot: receives livechat events (outgoing HTTP POST to HBF_BOT_EVENT_URL)
  • hbf-event-publisher: triggers automated flows (HBF_EVENT_PUBLISHER_URL)
  • MySQL: conversation, request, message, participant, settings persistence
  • Redis (optional): Socket.IO multi-instance adapter + response cache
  • S3-compatible storage: attachment uploads
  • Twilio: video call token generation
  • MS Teams: OAuth + Bot Framework callbacks and proactive notifications
  • Elastic APM (optional): performance monitoring

Running Locally​

# Install dependencies
npm install

# Run migrations
npm run migration:run

# Start in watch mode (APM disabled)
npm run start:dev

Tests​

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Coverage
npm run test:cov