Client–Relay Notifications

Client–relay protocol

Common Notification Rules

Notification Envelopes and Compatibility

Server notifications are sent only over WebSocket as JSON-RPC Notifications. jsonrpc MUST be "2.0", id MUST be omitted, and method is the notification name. When parameters are defined, params MUST be the complete parameter object. Parameterless notifications may omit params or use {}.

Ignore unknown outer envelope fields under WebSocket JSON-RPC; defined fields and params still follow their own validation rules.

Clients do not respond to notifications. Unknown notifications MUST be ignored for future extensibility. Notifications may be interleaved with JSON-RPC responses.

Connection and Session Requirements

Only device-session connections may establish subscriptions and receive device-state, message, channel, or group notifications. Notifications may coalesce, duplicate, or be lost and cannot replace the corresponding reads or synchronization methods.

Successful same-connection session renewal retains still-valid notification enablement and subscriptions. Current access permissions and device revocation rules continue to apply.

Notification Handling Rules

Notifications must satisfy connection identity, session, subscription, and object-binding requirements. Position or revision comparisons MUST be scoped to the same trusted network context, relay, resource, and current device's processing scope. Completed positions cannot be reused across accounts, channels, groups, or devices.

A notification carrying head may be ignored if it is no greater than the corresponding locally completed synchronization position. Other pending notifications may be coalesced into one catch-up. Receiving a notification or issuing a read does not advance position; the relevant read method determines advancement. Completion depends on its response and processing results. Filtering, deletion, or pruning may leave the last readable record below the notified head.

Without a comparable position or revision, notifications can only coalesce pending refresh needs for the same object. Identical parameters, an existing cache, or a just-completed read do not alone establish staleness. If list-change hints arrive after paginated reading starts and cannot be confirmed covered by that traversal, restart without a cursor; finishing remaining pages alone cannot clear the refresh need.

New hints received during a read remain pending and require catch-up unless coverage by that read can be confirmed. Read failure or incomplete processing likewise does not satisfy the need.

Filtering or coalescing notifications cannot clear known history gaps or other unsatisfied synchronization needs.

device.state.changed

After accepting new AccountDeviceState, the account's current home relay sends device.state.changed to its still-valid online device-session connections, including other connections established by the device that submitted the update. Account sessions receive none. Connections of devices removed by the new state are invalidated directly and receive none. Pre-stored state produces no notification.

Notification Parameters

Processing Rules

Within the same trusted network context and own-account scope, compare notification revision with complete device state locally verified and saved. A no-higher notification may be ignored. With no such state or a higher hint, call device.state.resolve to read complete own-device state, verify it, and update the cache.

Pending hints for one account may coalesce to the highest revision. Coverage may be confirmed only after a verified read result has revision no lower than the highest pending hint. A higher hint during the read, a failed read, or a still-lower result retains the need and requires catch-up under Notification handling rules.

The notification carries no complete state and proves no device state. Receipt MUST NOT directly advance verified local revision or change device permissions. Ignoring or coalescing MUST NOT clear other unsatisfied refresh needs.

message.timeline.changed

This notification is enabled only on WebSocket connections to the account's current home relay. On first successful auth.device.verify there, the relay MUST send the authentication success response before automatically enabling it.

Notification Parameters

Processing Rules

This is only a hint that unsynchronized records may exist for the current device. Handle it under Notification handling rules, calling message.timeline.sync when catch-up is needed. head may identify a record visible only to other devices, so reaching it cannot be the completion condition.

Clients are advised to call message.timeline.sync after first device authentication on the current home relay's WebSocket connection to catch records potentially missed before enablement. Renewal alone requires no additional synchronization. Determine position under Message timeline processing, and catch up from it after disconnection, notification loss, or relay restart. With no WSS endpoint or before reconnection, clients should synchronize periodically.