Real-time Messaging

The platform provides real-time communication through WebSocket connections. Messages, events, and notifications are delivered instantly to connected clients.

WebSocket connections

Clients (browsers, mobile apps) establish a persistent WebSocket connection to the platform. Once connected, the client can:

• Subscribe to event topics (conversations, notifications, task updates)
• Receive real-time events as they happen
• Unsubscribe from topics they no longer need

Connection lifecycle

1. Connect — the client opens a WebSocket connection (HTTP upgrade)
2. Authenticate — the connection is associated with the user's session
3. Subscribe — the client subscribes to topics of interest
4. Receive events — the server pushes events matching subscribed topics
5. Disconnect — on close, all subscriptions are cleaned up

Keep-alive

The platform maintains connection health through ping/pong frames:

• The server sends periodic pings
• Clients must respond with pongs within the timeout window
• Connections that fail to respond are closed and cleaned up

Topic subscriptions

Clients subscribe to topics that follow a hierarchical naming pattern:

events.{orgId}.{source}.{resource}.{event}.{resourceId}

Examples:

Wildcards (*) enable flexible subscriptions — subscribe to all events of a type, or narrow to a specific resource.

Message streaming

When an agent generates a response, the tokens are streamed in real time:

1. The assistant engine starts generating the response
2. As each token is produced, a message_stream event is published
3. Connected clients subscribed to the conversation topic receive each token
4. The response appears progressively in the UI

This provides a responsive experience — users see the agent's response as it's being generated rather than waiting for the complete response.

Event delivery

Real-time events follow this path:

Service publishes event
  → Event bus (NATS)
    → WebSocket server
      → Match against client subscriptions
        → Deliver to subscribed clients

The WebSocket server subscribes to the event bus and routes events to the appropriate connected clients based on their topic subscriptions.

Notifications

The notification system builds on real-time events:

• Platform events (new messages, task completions, etc.) are evaluated against notification rules
• Matching rules generate notifications with content, priority, and recipient
• Notifications are delivered through the appropriate channel:
  • WebSocket — for connected clients (instant)
  • Push — for mobile clients (via push notification services)
  • Email — for offline delivery

See Notifications for details on configuring notification rules.

Related concepts

• Rooms and Participants — the conversation structure
• Event System — the underlying event bus
• Notifications — event-driven user notifications