Connecting to Live Channels

“Channels” are the named streams that carry real-time events between the server and connected browsers. Subscribing to a channel is how a page receives the events relevant to it.

Channel Conventions

user.{id} — events for a single user (own notifications, own DMs).
tenant.{slug} — events visible to anyone in that tenant.
group.{name} — events for a security group.
record.{table}.{id} — changes to one specific record.
thread.{id} — chat thread messages.
dashboard.{id} — dashboard widget updates.
system — platform-wide announcements (rare; admin only).

Subscription Process

Browser opens WebSocket to /ws with its session cookie.
Server authenticates the connection.
Browser sends subscribe commands for each channel it wants.
Server validates each subscription against the user's permissions; rejects unauthorised channels.
Server starts sending events on accepted channels.
Browser unsubscribes when navigating away.

Permission Enforcement

Every channel has an implicit permission check:

user.{id} — only the user with that ID can subscribe.
record.{table}.{id} — only users with view access to that record.
tenant.{slug} — only users in that tenant.

Bypassing these checks is impossible — the server is the authority.

Worked Examples

User opens app: Subscribes to user.{me} for notifications, tenant.{my_tenant}.activity for feed updates.
User opens a customer record: Adds record.customers.{id} subscription; sees real-time edits from others.
User opens chat: Subscribes to thread.{id} for the active thread.
User opens dashboard: Subscribes to dashboard.{id} so live blocks update without reload.

Tip: Unsubscribe when leaving a page. Lingering subscriptions waste server resources and may deliver irrelevant events to stale UIs.