Communication Realtime Implementation

Scope (v1)

Realtime is an additive delta + notification layer over REST for:

• channel post stream updates
• channel discussion message updates

It is not the same thing as mobile push notification delivery:

• realtime updates flow over websocket rooms
• broadcast post push notifications are driven by explicit channel membership
• channel membership does not bypass access policy checks

Room Names

• Channel posts room: communication:channel:{channelId}:posts
• Discussion messages room: communication:discussion:{discussionId}:messages

Socket Client Events

• communication:join_channel_posts
  • payload: { "channelId": number }
• communication:leave_channel_posts
  • payload: { "channelId": number }
• communication:join_discussion
  • payload: { "channelId": number }
• communication:leave_discussion
  • payload: { "discussionId": number }
• communication:sync_channel_posts
  • payload: { "channelId": number, "sinceEventId"?: string, "limit"?: number }
• communication:sync_discussion
  • payload: { "channelId": number, "sinceEventId"?: string, "limit"?: number }

Join/Leave Authorization

• JWT is required for all communication websocket events.
• Channel post room join reuses channel read policy checks.
• Discussion room join reuses:
  • channel access checks
  • discussion enabled check
  • discussion feature requirement check (requiredFeatureKey)
  • discussion ban check

Important access rule:

• If a gated user loses channel entitlement, they cannot join channel or discussion realtime rooms for locked content.
• A joined user may still receive broadcast mobile push during the 7-day grace window, but realtime discussion access remains blocked until entitlement is restored.

Error codes from join/sync handlers:

• UNAUTHORIZED
• FORBIDDEN
• NOT_FOUND
• VALIDATION_ERROR
• SERVICE_UNAVAILABLE

Server Event Names

• communication.channel_post.created
• communication.channel_post.updated
• communication.channel_post.deleted
• communication.channel_post.pinned
• communication.discussion_message.created
• communication.discussion_message.updated
• communication.discussion_message.deleted
• communication.discussion_message.restored

Event Envelope

Every communication event payload follows:

{
	"eventId": "019d....",
	"eventType": "communication.channel_post.created",
	"occurredAt": "2026-03-17T10:15:00.000Z",
	"data": {}
}

Payload rules:

• delta only (no speculative fields)
• includes entity id + context id + timestamps + actor
• delete payloads are tombstones (isDeleted, deletedAt) instead of full object snapshots

Reconnect & Replay Flow

1. Connect/reconnect websocket.
2. Rejoin required communication rooms.
3. Call sync event with last processed sinceEventId.
4. Client dedupes by eventId and applies in order.
5. If replay fails or gap is detected, fallback to REST refetch.

Sequence Flow

Client Integration Checklist

• Keep REST as source of truth for initial/full state.
• Use realtime only for incremental UI updates.
• Store last eventId per joined room.
• On reconnect:
  • rejoin rooms
  • sync from last eventId
  • fallback to REST if needed.