Communication: hbf-lcm

1-hop view of how this service communicates with its siblings. For the full system view, see service-communication.md.

Calls Out To

Service	Protocol	Purpose	Key calls / queues
hbf-core	HTTP Bearer	User auth, org/tenant lookups, user groups, tags, contacts, chat sessions, translations, audit logs	20+ methods via CoreClientService
hbf-lcg	HTTP POST	Livechat lifecycle events	MESSAGE, CONVERSATION_BEGIN, CONVERSATION_END, CONVERSATION_TYPING, TRANSFER_REQUEST, REQUEST_MISSED via BotClientService -> HBF_BOT_EVENT_URL -> POST /events/helvia-livechat (LCG forwards to hbf-bot)
hbf-event-publisher	HTTP POST	Flow triggers	livechat-request-missed, livechat-conversation-finished via PublisherClientService -> HBF_EVENT_PUBLISHER_URL
MS Teams	OAuth + Bot Framework	Token exchange, bot callbacks	OAuth token exchange, Bot Framework activity callbacks
Twilio	HTTP	Video call support	Token generation, room management
S3/MinIO	HTTP	File attachment storage	Signed URL generation

Called By

Service	Protocol	How
hbf-bot	HTTP POST	POST /livechat-requests, POST /organizations/:orgId/livechat-messages, GET requests
hbf-lcg	HTTP POST	POST /livechat-requests (upstream livechat from Helvia, Genesys, Cisco, Zendesk)
hbf-console	Socket.IO	Message and event channels for agent connections
hbf-core	HTTP DELETE	DELETE /organizations/{orgId}/data, DELETE /organizations/:orgId/data-retention (cascade deletion)

Contracts

Inbound

HTTP (REST)

• POST /livechat-requests -- create request (LCM token)
• GET /users/:userId/livechat-requests -- query user requests (LCM token)
• GET /organizations/:orgId/livechat-requests -- query org requests (LCM token)
• POST /organizations/:orgId/livechat-messages -- post message (LCM token)
• GET /agent/organizations/:orgId/livechat-conversations -- list conversations (HBF token)
• GET /organizations/:orgId/livechat-conversations/:id -- conversation detail
• GET /organizations/:orgId/livechat-messages -- get messages (CSV/PDF export)
• POST /livechat-attachments -- upload attachment
• GET /organizations/:orgId/livechat-settings -- get settings
• PUT /organizations/:orgId/livechat-settings -- update settings
• GET, POST, PATCH, DELETE /organizations/:organizationId/user-groups/:userGroupId/business-hours -- business hours CRUD
• DELETE /organizations/:orgId/data-retention -- purge data (LCM token)

Socket.IO (browser-facing, hbf-console agents)

Inbound from agents:

• connection -- JWT auth
• message -- text/system message
• event -- REQUEST_CREATE, REQUEST_ACCEPT, CONVERSATION_JOIN, CONVERSATION_END, CONVERSATION_TYPING, CONVERSATION_READ, PARTICIPANT_FLAG, CONVERSATION_LEAVE

Outbound to agents:

• message -- broadcast
• event -- AUTHORIZATION_GRANTED, REQUEST_CREATE_ACK, NOTIFICATION, ERROR

Outbound

• hbf-lcg: POST {HBF_BOT_EVENT_URL} (value: http://hbf-lcg:<port>/events/helvia-livechat) -- { type: "MESSAGE"|"CONVERSATION_BEGIN"|"CONVERSATION_END"|"CONVERSATION_TYPING"|"TRANSFER_REQUEST"|"REQUEST_MISSED", data: CallbackEvent } (LCG transforms and forwards to hbf-bot via POST /livechat-events)
• hbf-event-publisher: POST /connectors/flows:trigger?triggerType=<type>&organizationId=<id>&tenantId=<id> -- event payload

Env vars:

• HBF_CORE_URL -> hbf-core
• HBF_BOT_EVENT_URL -> hbf-lcg (/events/helvia-livechat)
• HBF_EVENT_PUBLISHER_URL -> hbf-event-publisher
• REDIS_URL -> Redis (Socket.IO adapter)

Flows Involving This Service

• Live Chat Handover
• Message Processing