Real-time Chat

Enterprise Feature

Real-time chat is only available in the enterprise edition when both cibseven.webclient.modeler.enabled: true and cibseven.webclient.modeler.chat.enabled: true. See Enable / Disable.

The modeler includes a real-time chat panel for collaborating on diagrams. Users in the same room can send messages, see who is online, and attach comments to specific BPMN elements.

Transport

Available from 2.2.1

The configurable chat transport (cibseven.webclient.modeler.chat.transport) and long-polling mode are available from CIB seven 2.2.1. Earlier versions only support the websocket transport.

Chat supports two delivery transports, selected by the cibseven.webclient.modeler.chat.transport property:

Value Default Description
longpolling Yes Events are sourced from the shared database. Works correctly in single-instance and multi-pod deployments — no sticky routing or message broker required.
websocket No Events are pushed over a STOMP WebSocket (/ws/chat). Lower latency for single-instance deployments, but unreliable in multi-pod environments without sticky routing.

See Enable / Disable for the full configuration reference.

Long-Polling (default)

The client polls GET {basePath}/chat/{roomId}/poll?since={cursor}. The server holds the request for up to ~25 seconds and returns early as soon as there are new events; the client immediately re-polls. This gives near-real-time delivery without a persistent socket.

A presence heartbeat is recorded with every poll. Users appear online as long as they are actively polling and drop off the presence list approximately 60 seconds after their last poll.

WebSocket

Chat uses STOMP over WebSocket. Clients connect to:

ws://{host}/ws/chat

Authentication is performed on the STOMP CONNECT frame:

CONNECT
Authorization: Bearer <token>

The server validates the token and associates the authenticated user with the WebSocket session for its entire lifetime.

Topics

Topic Direction Description
/topic/chat/{roomId} Subscribe Receive new, edited, and deleted messages in real time
/topic/chat/{roomId}/presence Subscribe Receive live updates of who is currently online in the room
/app/chat/{roomId} Publish Send a new message to the room

Room ID

The roomId is a composite key that combines context and diagram ID:

{context}:{diagramId}

For example: modeler:abc123-def456.

The context prefix namespaces the room, ensuring diagrams from different parts of the application do not share a chat history.

Sending a Message

In WebSocket mode, publish a JSON payload to /app/chat/{roomId}:

{
  "content": "Hello, team!",
  "elementId": "Task_1"
}

In long-polling mode, POST the same payload to the REST endpoint:

POST {basePath}/chat/{roomId}
Field Required Description
content Yes Message text (must not be blank)
elementId No BPMN element ID to attach the message to a specific element

Presence

The set of users currently active in a room is tracked per transport:

  • Long-polling — presence is backed by the database (chat_presence table). Each poll refreshes the user’s last-seen timestamp; users with no activity for more than ~60 seconds are considered offline.
  • WebSocket — presence is tracked in-memory. A user appears when they subscribe to /topic/chat/{roomId}/presence and is removed on unsubscribe or disconnect.

The current presence snapshot can be retrieved via the REST API — see REST API.

Message History

Previous messages are not pushed on initial connect. Fetch history on load via the REST endpoint:

GET {basePath}/chat/{roomId}/history

The history endpoint returns only live messages — soft-deleted messages (removed by users) are excluded. See REST API for parameters.

Chat Tab Behavior

The Properties panel in the modeler shows a Properties / Chat tab bar when chat.enabled: true.

Unsaved diagrams — The Chat tab is visually disabled and shows the tooltip “Save the diagram to use the chat”. Clicking it has no effect. The Properties tab always remains accessible.

Switching diagrams — If the Chat tab is open and the user switches to a diagram that has not been saved yet, the panel automatically collapses back to the Properties tab. This prevents the user from being left with an open but non-functional chat panel on an unsaved diagram.

Once a diagram is saved, the Chat tab becomes active and the connection is established when it is selected.

Database

Messages are persisted in the chat_messages table. Deleted messages are soft-deleted: the row is retained as a tombstone (content cleared) so the long-polling transport can detect the deletion and propagate it to all connected clients.

Active presence (long-polling mode) is tracked in the chat_presence table.

See Database Schema.

On this Page: