Skip to content
Chatto v0.5.0

Realtime WebSocket Protocol

Chatto exposes realtime updates at GET /api/realtime using binary protobuf frames from chatto.realtime.v1.

Read the Realtime Protocol Overview before you implement the connection lifecycle, snapshot processing, event processing, targeted cursor-bounded reads, or reconnect behavior. Follow Use Realtime From TypeScript for a complete browser example.

This page separates protocol frames from the public event catalogue. The RealtimeEvent section lists every public event variant.

Realtime frames are documented separately from ConnectRPC services because they are exchanged over a long-lived WebSocket session rather than /api/connect RPC methods.

These messages and enums control the WebSocket lifecycle, snapshots, recovery, liveness, errors, and closure.

Confirms that recovery is complete and live delivery has begun.

Clients can retain cursor after they apply every preceding event.

FieldTypeDescription
cursorstringOpaque cursor at the recovery-to-live handoff boundary.
recoveryRealtimeRecoveryActual recovery result, including a successful replay with no events.

Close instruction sent before the socket closes when possible.

FieldTypeDescription
codeRealtimeCloseCodeStable machine-readable close code.
messagestringSafe human-readable close message.
reconnectboolWhether the client should reconnect automatically.
retry_aftergoogle.protobuf.DurationSuggested delay before reconnect.

Application-level heartbeat.

FieldTypeDescription
cursoroptional stringFresh resume cursor for the latest replay boundary delivered on this socket. A client can retain it only after all earlier frames have been applied.

Server-to-client frame for Chatto’s protobuf WebSocket realtime protocol.

FieldTypeDescription
frame.eventRealtimeEventOne authorized public event copy.
frame.heartbeatRealtimeHeartbeatApplication-level heartbeat used for liveness checks.
frame.closeRealtimeCloseServer-requested close with reconnect guidance.
frame.caught_upRealtimeCaughtUpConfirms that recovery reached the live-stream boundary.
frame.snapshotRealtimeSnapshotOne exact authorized server-content snapshot.

One authorized snapshot of the current bounded server content.

The server sends at most one snapshot before caught_up. The client must discard the snapshot if the socket closes before caught_up. List values replace the complete local family. Large and paginated resources, such as message history, are not part of the snapshot and remain available through ConnectRPC.

FieldTypeDescription
serverchatto.api.v1.ServerPublicProfileCurrent public server profile.
roomsrepeated chatto.api.v1.RoomWithViewerStateAll rooms visible to the caller at the snapshot boundary.
room_groupsrepeated chatto.api.v1.RoomGroupAll room groups visible to the caller at the snapshot boundary.
usersrepeated chatto.api.v1.DirectoryMemberThe viewer and public users referenced by another snapshot family.
active_callsrepeated chatto.api.v1.ActiveCallAll active calls visible to the caller at the snapshot boundary.

Starts one authorized public realtime subscription.

The client sends this message as the first binary WebSocket message. The client does not send more application messages on the socket.

FieldTypeDescription
protocol_versionuint32Behavioral protocol version requested by the client. The only supported version is 4.
bearer_tokenoptional stringOptional bearer token. When present, it takes precedence over cookie auth.
resume_cursoroptional stringOpaque cursor from a previously received replayable event or caught_up frame. A usable cursor receives bounded authorized events after that position. Cursors expire 15 minutes after issue.
initial_stateRealtimeInitialStateRequired fallback when the cursor is absent or cannot resume safely.

Stable server-requested close category.

NameNumberDescription
REALTIME_CLOSE_CODE_UNSPECIFIED0Invalid or unknown close code.
REALTIME_CLOSE_CODE_INVALID_REQUEST1The subscription message is malformed or contains an invalid value.
REALTIME_CLOSE_CODE_UNSUPPORTED_PROTOCOL2The requested behavioral protocol version is not supported.
REALTIME_CLOSE_CODE_TEMPORARILY_UNAVAILABLE3The server cannot accept or continue a realtime session at present.
REALTIME_CLOSE_CODE_AUTHENTICATION_REQUIRED4The caller is no longer authenticated.
REALTIME_CLOSE_CODE_SESSION_RENEWAL_REQUIRED5The caller must renew its session before reconnecting.
REALTIME_CLOSE_CODE_RESYNC_REQUIRED6The client must discard its cursor and synchronize current state again.
REALTIME_CLOSE_CODE_SESSION_TERMINATED7The user’s session ended and the client must return to sign-in.
REALTIME_CLOSE_CODE_PRIVILEGED_MODE_EXPIRED8Privileged mode expired. Reconnect and refresh effective viewer and room permissions.

Startup behavior when a subscription cannot resume from its cursor.

NameNumberDescription
REALTIME_INITIAL_STATE_UNSPECIFIED0Invalid value. The server rejects subscriptions that use it.
REALTIME_INITIAL_STATE_LIVE_ONLY1Start at the current event boundary without sending current resources.
REALTIME_INITIAL_STATE_SNAPSHOT2Send an exact authorized snapshot before later public events.

How the server reached the live-delivery boundary.

NameNumberDescription
REALTIME_RECOVERY_UNSPECIFIED0Invalid value. The server always supplies a recovery result.
REALTIME_RECOVERY_RESUMED1The requested cursor was accepted and all available authorized events followed it.
REALTIME_RECOVERY_SNAPSHOT2The server sent a replacement snapshot.
REALTIME_RECOVERY_LIVE_ONLY3The server started at the current boundary without past events or resources.

These messages and enums define the authorized semantic events that the server can deliver. An event can contain a resume cursor when the server can replay it. Other events are cursorless.

One authorized public event with its optional cursor.

Each payload uses a realtime-owned public message. The union is the public event catalogue. An internal event that is absent from this union is not part of the realtime API. The server creates a fresh caller-specific value after authorization. An event has a resume cursor when it can be replayed. An event without a cursor is safe to miss, or its state can be restored from a snapshot or a ConnectRPC resource.

FieldTypeDescription
idstringUniversal event identifier (NanoID).
created_atgoogle.protobuf.TimestampTime when the source event was created.
actor_idoptional stringID of the user that caused the event. Absence means no user actor.
cursoroptional stringOpaque cursor safe to retain after this complete event is accepted.
event.room_createdRoomCreatedEventNo field description provided.
event.room_updatedRoomUpdatedEventNo field description provided.
event.room_deletedRoomDeletedEventNo field description provided.
event.room_archivedRoomArchivedEventNo field description provided.
event.room_unarchivedRoomUnarchivedEventNo field description provided.
event.room_universal_changedRoomUniversalChangedEventNo field description provided.
event.room_slow_mode_changedRoomSlowModeChangedEventNo field description provided.
event.room_threading_mode_changedRoomThreadingModeChangedEventNo field description provided.
event.user_joined_roomUserJoinedRoomEventNo field description provided.
event.user_left_roomUserLeftRoomEventNo field description provided.
event.voice_call_participant_joinedVoiceCallParticipantJoinedEventNo field description provided.
event.voice_call_participant_leftVoiceCallParticipantLeftEventNo field description provided.
event.voice_call_startedVoiceCallStartedEventNo field description provided.
event.voice_call_endedVoiceCallEndedEventNo field description provided.
event.message_postedMessagePostedEventNo field description provided.
event.message_editedMessageEditedEventNo field description provided.
event.message_retractedMessageRetractedEventNo field description provided.
event.message_pinnedMessagePinnedEventNo field description provided.
event.message_unpinnedMessageUnpinnedEventNo field description provided.
event.thread_createdThreadCreatedEventNo field description provided.
event.asset_processing_startedAssetProcessingStartedEventNo field description provided.
event.asset_processing_succeededAssetProcessingSucceededEventNo field description provided.
event.asset_processing_failedAssetProcessingFailedEventNo field description provided.
event.asset_deletedAssetDeletedEventNo field description provided.
event.server_motd_changedServerMotdChangedEventNo field description provided.
event.user_account_createdUserAccountCreatedEventNo field description provided.
event.user_profile_changedUserProfileChangedEventNo field description provided.
event.user_account_deletedUserAccountDeletedEventNo field description provided.
event.reaction_addedReactionAddedEventNo field description provided.
event.reaction_removedReactionRemovedEventNo field description provided.
event.viewer_preferences_changedViewerPreferencesChangedEventNo field description provided.
event.thread_viewer_state_changedThreadViewerStateChangedEventNo field description provided.
event.server_profile_changedServerProfileChangedEventNo field description provided.
event.user_typingUserTypingEventNo field description provided.
event.presence_changedPresenceChangedEventNo field description provided.
event.notification_occurrences_changedNotificationOccurrencesChangedEventNo field description provided.
event.notification_unread_state_changedNotificationUnreadStateChangedEventNo field description provided.
event.room_read_state_changedRoomReadStateChangedEventNo field description provided.
event.room_layout_changedRoomLayoutChangedEventNo field description provided.
event.role_createdRoleCreatedEventNo field description provided.
event.role_updatedRoleUpdatedEventNo field description provided.
event.role_deletedRoleDeletedEventNo field description provided.
event.roles_reorderedRolesReorderedEventNo field description provided.
event.role_assignedRoleAssignedEventNo field description provided.
event.role_revokedRoleRevokedEventNo field description provided.
event.role_permissions_changedRolePermissionsChangedEventNo field description provided.
event.viewer_permissions_changedViewerPermissionsChangedEventNo field description provided.
event.viewer_presence_preference_changedViewerPresencePreferenceChangedEventNo field description provided.
event.room_invitation_createdRoomInvitationCreatedEventNo field description provided.
event.room_invitation_acceptedRoomInvitationAcceptedEventNo field description provided.
event.room_invitation_declinedRoomInvitationDeclinedEventNo field description provided.
event.room_notice_changedRoomNoticeChangedEventNo field description provided.
event.user_account_deactivation_changedUserAccountDeactivationChangedEventNo field description provided.
event.room_membership_events_visibility_changedRoomMembershipEventsVisibilityChangedEventNo field description provided.

AllMessageMention identifies a room-wide mention.

AssetDeletedEvent reports a deleted asset.

FieldTypeDescription
asset_idstringNo field description provided.
room_idstringRoom containing the affected message.
message_event_idstringMessage that owns the asset, including a deleted derivative asset.

AssetProcessingFailedEvent reports failed message-asset processing.

FieldTypeDescription
asset_idstringNo field description provided.
failure_codeAssetProcessingFailureCodeNo field description provided.
message_event_idstringNo field description provided.
room_idstringRoom containing the affected message.

AssetProcessingStartedEvent reports that message-asset processing started.

FieldTypeDescription
asset_idstringNo field description provided.
message_event_idstringNo field description provided.
room_idstringRoom containing the affected message.

AssetProcessingSucceededEvent reports successful message-asset processing. Read the message resource for current attachments and processed video data.

FieldTypeDescription
asset_idstringNo field description provided.
message_event_idstringNo field description provided.
room_idstringRoom containing the affected message.

DirectUserMention identifies a direct user mention.

FieldTypeDescription
user_idstringNo field description provided.

HereMessageMention identifies a presence-scoped mention.

MessageEditedEvent reports changed message content or metadata.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.

MessageMention identifies one distinct mention target. Role, here, and all targets occur once, regardless of the number of recipients. Targets with no resolved recipients are omitted. Recipient decisions are from message creation, including during replay; clients must not infer them from current membership.

FieldTypeDescription
cause.directDirectUserMentionNo field description provided.
cause.roleRoleMessageMentionNo field description provided.
cause.hereHereMessageMentionNo field description provided.
cause.allAllMessageMentionNo field description provided.
includes_viewerboolTrue if this target included the authenticated caller when the message was posted.

MessagePinnedEvent reports a newly pinned message.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.

MessagePostedEvent reports a new room message.

FieldTypeDescription
room_idstringNo field description provided.
in_reply_tostringNo field description provided.
thread_root_event_idstringRoot message ID for a thread reply. Empty for a room-level message.
echo_of_event_idstringNo field description provided.
echo_from_thread_root_event_idstringNo field description provided.
mentionsrepeated MessageMentionDistinct mention targets, without expanded role or broadcast recipients.
body_plaintextoptional stringPlaintext message text. The field is absent after key shredding.
room_kindchatto.api.v1.RoomKindImmutable room kind. Direct messages do not require a mention to address a bot.

MessageRetractedEvent reports a retracted message.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.

MessageUnpinnedEvent reports a message that is no longer pinned.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.

NotificationOccurrencesChangedEvent reports that the caller’s current notification occurrences changed and requests an authoritative resource read.

FieldTypeDescription
created_notification_idoptional stringID of a newly created notification, including read notifications and creations during Do Not Disturb. Absent for updates and removals. This is a best-effort live hint, not a sound instruction or durable delivery. Clients decide whether to alert after they read current notification state.

NotificationUnreadStateChangedEvent reports that the caller’s notification unread state changed and requests authoritative notification and room reads.

FieldTypeDescription
room_idstringNo field description provided.
thread_root_event_idstringEvent ID of the affected thread root, or empty for room state.

PresenceChangedEvent reports the actor’s current presence.

FieldTypeDescription
statuschatto.api.v1.PresenceStatusNo field description provided.

ReactionAddedEvent reports a new message reaction.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.
emojistringNo field description provided.

ReactionRemovedEvent reports a removed message reaction.

FieldTypeDescription
room_idstringNo field description provided.
message_event_idstringNo field description provided.
emojistringNo field description provided.

A user was assigned a role. The named user’s clients must discard private cached data and load current authorized state. Other viewers update member role lists without a full reload.

FieldTypeDescription
user_idstringUser whose assignment changed.
role_namestringStable role name.

A public role was created. Read its current metadata with RoleService.

FieldTypeDescription
role_namestringStable role name.

A role was deleted. Remove it from role catalogues and member role lists. Clients retaining this role for their viewer must discard private cached data and load current authorized state before displaying it again.

FieldTypeDescription
role_namestringStable name of the deleted role.

RoleMessageMention identifies the role that caused a mention.

FieldTypeDescription
role_namestringNo field description provided.

A role’s permission decisions changed. Clients whose viewer has this role must discard private cached data and load current authorized state. The implicit everyone role applies to every viewer. Private scopes and permission decisions are not included. Read current decisions through authorized APIs.

FieldTypeDescription
role_namestringStable role name.

A user’s role assignment was removed. The named user’s clients must discard private cached data and load current authorized state.

FieldTypeDescription
user_idstringUser whose assignment changed.
role_namestringStable role name.

Public role metadata changed. Read its current metadata with RoleService. This event does not change permission decisions.

FieldTypeDescription
role_namestringStable role name.

Custom roles changed display order. Permission decisions are unchanged.

FieldTypeDescription
role_namesrepeated stringCustom role names in ascending display position.

RoomArchivedEvent reports a room that became archived.

FieldTypeDescription
room_idstringNo field description provided.

RoomCreatedEvent reports a new room that is visible to the caller.

FieldTypeDescription
room_idstringNo field description provided.
namestringNo field description provided.
descriptionstringNo field description provided.
kindchatto.api.v1.RoomKindNo field description provided.
universalboolNo field description provided.
threading_modechatto.api.v1.RoomThreadingModeNo field description provided.

RoomDeletedEvent reports a deleted room.

FieldTypeDescription
room_idstringNo field description provided.

An invitation accepted. Delivered only to its sender and recipient.

FieldTypeDescription
room_idstringNo field description provided.
invitation_idstringNo field description provided.

An invitation created. Delivered only to its sender and recipient.

FieldTypeDescription
room_idstringNo field description provided.
invitation_idstringNo field description provided.

An invitation declined. Delivered only to its sender and recipient.

FieldTypeDescription
room_idstringNo field description provided.
invitation_idstringNo field description provided.

RoomLayoutChangedEvent reports a change to room groups, their entries, or order. Refresh RoomDirectoryService.ListRoomGroups with this event’s cursor as the minimum boundary. The event contains no room IDs or other hidden layout data.

RoomMembershipEventsVisibilityChangedEvent

Section titled “RoomMembershipEventsVisibilityChangedEvent”

RoomMembershipEventsVisibilityChangedEvent changes how clients display room join/leave activity, including history. Clients must still process membership events when this setting is false.

FieldTypeDescription
room_idstringNo field description provided.
show_membership_eventsboolNo field description provided.

RoomNoticeChangedEvent asks current room members to read the latest notice. It covers corrections, publication, republishing, and clear operations.

FieldTypeDescription
room_idstringNo field description provided.

RoomReadStateChangedEvent reports the caller’s current room read state.

FieldTypeDescription
room_idstringNo field description provided.

RoomSlowModeChangedEvent reports the current slow-mode interval.

FieldTypeDescription
room_idstringNo field description provided.
slow_mode_secondsuint32No field description provided.
thread_slow_mode_secondsoptional uint32Independent interval within each thread. Zero disables it.

RoomThreadingModeChangedEvent reports the current room threading policy.

FieldTypeDescription
room_idstringNo field description provided.
threading_modechatto.api.v1.RoomThreadingModeNo field description provided.

RoomUnarchivedEvent reports a room that became active again.

FieldTypeDescription
room_idstringNo field description provided.

RoomUniversalChangedEvent reports the current universal-membership setting.

FieldTypeDescription
room_idstringNo field description provided.
universalboolNo field description provided.

RoomUpdatedEvent reports changed room metadata.

FieldTypeDescription
room_idstringNo field description provided.
namestringNo field description provided.
descriptionstringNo field description provided.

ServerMotdChangedEvent reports the current message of the day.

FieldTypeDescription
motdstringNo field description provided.

ServerProfileChangedEvent reports that the public server profile changed. Read ServerService with this event’s resume cursor as the minimum boundary.

ThreadCreatedEvent reports a new message thread.

FieldTypeDescription
room_idstringNo field description provided.
thread_root_event_idstringNo field description provided.

ThreadViewerStateChangedEvent reports the caller’s current thread state.

FieldTypeDescription
room_idstringNo field description provided.
thread_root_event_idstringNo field description provided.
is_followingboolNo field description provided.

UserAccountCreatedEvent reports a new public user account.

FieldTypeDescription
user_idstringNo field description provided.
is_botboolNo field description provided.

Reports a reversible account access change. Administrative details are private.

FieldTypeDescription
user_idstringNo field description provided.
deactivatedboolNo field description provided.

UserAccountDeletedEvent reports a deleted user account.

FieldTypeDescription
user_idstringNo field description provided.

UserJoinedRoomEvent reports that the actor joined a room.

FieldTypeDescription
room_idstringNo field description provided.

UserLeftRoomEvent reports that the actor left a room.

FieldTypeDescription
room_idstringNo field description provided.

UserProfileChangedEvent reports that the current public user resource changed. Read the user through UserService with this event’s resume cursor as the minimum boundary.

FieldTypeDescription
user_idstringNo field description provided.

UserTypingEvent reports current typing activity for the event actor. Track each actor separately for each room and thread. Clear the indicator 6 seconds after the last received typing event, or when that actor posts a message in the same room or thread. No stop-typing event is sent.

FieldTypeDescription
room_idstringNo field description provided.
thread_root_event_idoptional stringNo field description provided.

The authenticated viewer’s permission decisions may have changed. This also covers changes to a bot’s owner permission ceiling. Delivered only to the affected viewer. Discard private cached data and load current authorized state before displaying it again. The connection itself remains open.

ViewerPreferencesChangedEvent reports that the caller’s private user preferences changed. Read ViewerService with this event’s resume cursor as the minimum boundary.

Delivered only to the account whose private availability choice changed. Refetch MyAccountService.GetPresencePreference to obtain the current choice.

VoiceCallEndedEvent reports the end of a call session.

FieldTypeDescription
room_idstringNo field description provided.
call_idstringNo field description provided.

VoiceCallParticipantJoinedEvent reports that the actor joined a call session.

FieldTypeDescription
room_idstringNo field description provided.
call_idstringNo field description provided.

VoiceCallParticipantLeftEvent reports that the actor left a call session.

FieldTypeDescription
room_idstringNo field description provided.
call_idstringNo field description provided.

VoiceCallStartedEvent reports a new call session.

FieldTypeDescription
room_idstringNo field description provided.
call_idstringNo field description provided.

AssetProcessingFailureCode identifies a stable processing failure class.

NameNumberDescription
ASSET_PROCESSING_FAILURE_CODE_UNSPECIFIED0The failure class is not known.
ASSET_PROCESSING_FAILURE_CODE_PROCESSING_FAILED1Asset processing failed without a more specific public reason.
ASSET_PROCESSING_FAILURE_CODE_SOURCE_MISSING2The source asset was not available.