Skip to content
Chatto v0.5.0

RoomService

Chatto exposes this service below /api/connect.

Shared message and enum definitions are documented in Shared Types And Enums.

Manages room-scoped operations for the current user.

RoomService owns operations whose authorization and state are primarily scoped to one room, including lifecycle, membership, moderation, room timeline reads, room read state, attachments, and live typing. Resource-specific services should still be preferred when an operation is not naturally room-scoped or when the resource needs an independent CRUD/batch surface.

Reads a channel notice. Requires current room membership, including in archived rooms. A room without a notice returns an empty body.

POST /api/connect/chatto.api.v1.RoomService/GetNotice

Reads the current channel notice, including its version when cleared.

FieldTypeDescription
room_idstringNo field description provided.

No message description provided.

FieldTypeDescription
noticeRoomNoticeNo field description provided.

Publishes, corrects, or explicitly republishes a notice. Requires current membership and room.manage-notice. Archived rooms reject writes. A stale expected_version returns ABORTED; preserve the draft and reload before retry.

POST /api/connect/chatto.api.v1.RoomService/PublishNotice

Publishes or replaces a notice. Replacements preserve dismissals unless republish is true. A new publication always has a fresh dismissal revision.

FieldTypeDescription
room_idstringNo field description provided.
bodystringNo field description provided.
expected_versionstringNo field description provided.
republishboolTrue announces the replacement to members who dismissed the previous notice. False preserves dismissals. A first publication always announces the notice.

No message description provided.

FieldTypeDescription
noticeRoomNoticeNo field description provided.

Clears a notice under the same access and version rules as PublishNotice.

POST /api/connect/chatto.api.v1.RoomService/ClearNotice

Clears the current notice without removing its concurrency version.

FieldTypeDescription
room_idstringNo field description provided.
expected_versionstringNo field description provided.

No message description provided.

FieldTypeDescription
noticeRoomNoticeNo field description provided.

Reads the current viewer’s stored marker without changing it. Requires the same membership and read access as MarkRoomAsRead. Missing resources return NOT_FOUND; inaccessible resources return PERMISSION_DENIED.

POST /api/connect/chatto.api.v1.RoomService/GetRoomReadState

Request current room read state without changing it.

FieldTypeDescription
room_idstringRoom ID.

Current room read state, including an absent marker when none is stored.

FieldTypeDescription
stateRoomReadStateState for the requested room and viewer.

Reads up to 100 states under the same authorization as GetRoomReadState. Missing and inaccessible resources are omitted; duplicates use first-seen order.

POST /api/connect/chatto.api.v1.RoomService/BatchGetRoomReadStates

Request room read states. Duplicates are removed in first-seen order.

FieldTypeDescription
room_idsrepeated stringUp to 100 room IDs. Missing or inaccessible rooms are omitted.

Accessible room read states in first-seen request order.

FieldTypeDescription
statesrepeated RoomReadStateStates for the current viewer. An absent marker does not omit the state.

Creates a new channel room in a room group. The caller must be allowed to create rooms in the target group.

POST /api/connect/chatto.api.v1.RoomService/CreateRoom

Request to create a channel room.

FieldTypeDescription
namestringRequired. Visible 1–30-code-point Unicode name of the new channel room. The server trims and stores it in NFC form. Control characters and Unicode line or paragraph separators are rejected.
descriptionstringOptional room description.
group_idstringRequired. Room group that should contain the new channel.
universalboolWhether the new channel should grant effective membership to eligible server members.
threading_modeRoomThreadingModeThreading policy for the new channel. UNSPECIFIED selects ENABLED.

Result of creating a room.

FieldTypeDescription
roomRoomCreated room.

Updates a room’s editable metadata. The caller must be allowed to manage rooms. Direct-message rooms cannot be universal.

POST /api/connect/chatto.api.v1.RoomService/UpdateRoom

Request to update a room’s editable metadata. update_mask selects editable fields to apply or reset. Fields outside the mask stay unchanged.

FieldTypeDescription
room_idstringRequired. Room to update.
nameoptional stringNew visible 1–30-code-point Unicode room name, when changing it. The server trims and stores it in NFC form. Control characters and Unicode line or paragraph separators are rejected.
descriptionoptional stringNew room description, when changing it. Empty clears the description.
universaloptional boolNew universal membership state, when changing it. Direct-message rooms cannot be universal.
slow_mode_secondsoptional uint32New per-user root posting interval in seconds. Zero disables slow mode. The maximum supported interval is six hours. Direct-message rooms cannot use slow mode.
threading_modeoptional RoomThreadingModeNew threading policy. Direct-message rooms cannot set this field, and an explicitly supplied UNSPECIFIED or unknown value is rejected.
update_maskgoogle.protobuf.FieldMaskEditable fields to apply or reset: name, description, universal, slow_mode_seconds, threading_mode, thread_slow_mode_seconds, show_membership_events. Omit to infer populated fields; * selects all editable fields. An explicit empty mask is invalid. Unselected values are ignored. Selected absent values reset the field to its default, subject to field validation.
thread_slow_mode_secondsoptional uint32Per-user interval within each thread. The root starts its author’s timer. Zero disables it. Updating this field does not change the root interval.
show_membership_eventsoptional boolWhether clients show join/leave activity in this channel’s history and live timeline. Requires room.manage. Selecting an absent value resets to true.

Result of updating a room.

FieldTypeDescription
roomRoomUpdated room.

Archives a room so it is hidden from active room lists. The caller must be allowed to manage rooms.

POST /api/connect/chatto.api.v1.RoomService/ArchiveRoom

Request to archive a room.

FieldTypeDescription
room_idstringRequired. Room to archive.

Result of archiving a room.

FieldTypeDescription
roomRoomArchived room.

Restores an archived room to active room lists. The caller must be allowed to manage rooms.

POST /api/connect/chatto.api.v1.RoomService/UnarchiveRoom

Request to unarchive a room.

FieldTypeDescription
room_idstringRequired. Room to unarchive.

Result of unarchiving a room.

FieldTypeDescription
roomRoomUnarchived room.

Joins the room as the current user when room permissions allow it.

POST /api/connect/chatto.api.v1.RoomService/JoinRoom

Request to join a room as the current user.

FieldTypeDescription
room_idstringRequired. Room to join.

Result of joining a room.

FieldTypeDescription
roomRoomJoined room.

Joins every unarchived room in a group that the current user can join. Already-joined and non-joinable rooms are skipped.

POST /api/connect/chatto.api.v1.RoomService/JoinRoomGroup

Request to join all joinable rooms in one room group.

FieldTypeDescription
group_idstringRequired. Room group whose rooms should be joined.

Result of joining all joinable rooms in one room group.

FieldTypeDescription
joined_room_idsrepeated stringRoom IDs that transitioned from not joined to joined.

Starts a direct-message room for the current human user and the requested participant set, or fetches its existing DM. message.post is required only when the DM must be created. A valid request from a bot receives PERMISSION_DENIED and cannot use this RPC to fetch an existing DM. New DMs support the caller and at most one other user. New group DMs receive INVALID_ARGUMENT; use a channel room instead. Existing group DMs can still be fetched.

POST /api/connect/chatto.api.v1.RoomService/StartDM

Request to start a direct-message room, or fetch an existing one. Human and bot callers need message.post at DM scope to create a room. Participants can fetch an existing DM without message.post. New DMs have at most two distinct participants, including the caller. Larger new participant sets receive INVALID_ARGUMENT. Use a channel room for new group conversations. Existing group DMs remain accessible.

FieldTypeDescription
participant_idsrepeated stringOther participants to include in the direct-message room. The current user is always included by the server. An empty list creates or fetches the caller’s self-DM.

Result of starting or fetching a direct-message room.

FieldTypeDescription
roomRoomDirect-message room for the participant set.

Leaves the room as the current user. Direct-message and universal rooms cannot be left.

POST /api/connect/chatto.api.v1.RoomService/LeaveRoom

Request to leave a room as the current user.

FieldTypeDescription
room_idstringRequired. Room to leave.

Result of leaving a room.

Lists effective room member IDs in ascending ID order. Resolve user details with UserService.BatchGetUsers. Existing members and room.manage holders may list a channel room; other nonmembers need both room.list and room.join.

POST /api/connect/chatto.api.v1.RoomService/ListMembers

Request for members of one room.

FieldTypeDescription
room_idstringRequired. Room whose effective members should be listed. Existing members and room.manage holders may list a channel room; other nonmembers need both room.list and room.join.
searchstringOptional case-insensitive search against login and display name.
pagePageRequestDefaults to 250 results when absent or limit is zero. Maximum: 500.
presence_statusesrepeated PresenceStatusOptional status filter applied before pagination. Empty means all statuses. Select ONLINE, AWAY, and DO_NOT_DISTURB for all connected members. Presence can change between pages; use realtime updates to keep it current.

Room membership IDs. Resolve profiles with UserService.BatchGetUsers. Empty searches do not read user profiles. Search results require profile reads to match names. Both paths use ascending user ID order.

FieldTypeDescription
user_idsrepeated stringCurrent member IDs in ascending order. Missing or deleted users are omitted.
pagePageInfoPage metadata for the members that match both filters.

Gets one effective member, including automatic universal membership. Channel-room members, room.manage holders, and user.manage-accounts holders may read members. Bot owners and bot.manage holders may read their target bots only. DMs require caller membership. Returns NOT_FOUND for nonmembers.

POST /api/connect/chatto.api.v1.RoomService/GetMember

Request one member of one room by stable user ID.

FieldTypeDescription
room_idstringRequired room ID.
user_idstringRequired target user ID.

Room member response.

FieldTypeDescription
memberDirectoryMemberRequested room member.

Gets effective member rows for the requested accounts. Uses the same authorization as GetMember; omits unknown accounts and nonmembers.

POST /api/connect/chatto.api.v1.RoomService/BatchGetMembers

Request room member rows for a set of stable user IDs.

FieldTypeDescription
room_idstringRequired room ID.
user_idsrepeated stringRequired target user IDs. Unknown IDs and users that are not members of the room are omitted from the response.

Batch room member response.

FieldTypeDescription
membersrepeated DirectoryMemberFound members. The server preserves first-seen request order and de-duplicates repeated IDs.

Adds an account as an explicit channel-room member. room.manage for this room or user.manage-accounts overrides the target’s missing room.join. Bot owners and bot.manage holders may also add bots, but without either override the acting human needs effective room.join. The bot’s own room.join is required only when the bot joins itself through JoinRoom. Preserves permission grants. Suspensions, archived, universal, and DM rooms prevent adding.

POST /api/connect/chatto.api.v1.RoomService/AddMember

Request to add a user to a channel room.

FieldTypeDescription
room_idstringRequired. Channel room to add the user to.
user_idstringRequired. User to add as an explicit room member.

Result of adding a user to a room.

FieldTypeDescription
memberDirectoryMemberAdded room member.

Removes an explicit channel-room member. Requires room.manage for this room, user.manage-accounts, ownership of the target bot, or bot.manage. Removal is allowed after room.join is lost and from archived rooms. Preserves permission grants. Universal and DM membership cannot be edited.

POST /api/connect/chatto.api.v1.RoomService/RemoveMember

Request to remove a user from a channel room.

FieldTypeDescription
room_idstringRequired. Channel room to remove the user from.
user_idstringRequired. User to remove from the room’s explicit members.

Result of removing a user from a room.

FieldTypeDescription
removedboolTrue when an explicit room membership was removed by this call.

Lists active channel room suspensions. Requires server-scope room.remove-member.

POST /api/connect/chatto.api.v1.RoomService/ListSuspensions

Request to list active room suspensions.

FieldTypeDescription
room_idstringOptional channel room filter. Empty lists active suspensions across all rooms.
pagePageRequestDefaults to 50 results when absent or limit is zero. Maximum: 100.

Active room suspensions visible to the current moderator.

FieldTypeDescription
suspensionsrepeated RoomSuspensionActive suspensions by creation time, newest first; equal times use event ID in ascending order.
pagePageInfoPage metadata.

Lists current message-owned room attachments. Authentication and room membership are required. Attachments also require message.read or a matching thread relationship with message.read-interactions. The server omits attachments from inaccessible threads. Returns PERMISSION_DENIED when the room is inaccessible to the caller.

POST /api/connect/chatto.api.v1.RoomService/ListRoomAttachments

Request for room-scoped attachment list pages.

FieldTypeDescription
room_idstringRequired room ID.
thumbnailImageTransformOptionsThumbnail URL options. Defaults are applied when absent.
pagePageRequestDefaults to 50 results when absent or limit is zero. Maximum: 100.

Room-scoped attachment list response.

FieldTypeDescription
attachmentsrepeated RoomAttachmentListItemCurrent attachments in newest message order.
pagePageInfoPage metadata.

Lists current pinned messages in a channel room. Room membership plus message.read or message.read-interactions are required. The server omits pins from threads that the caller cannot read. Direct-message rooms do not support pins.

POST /api/connect/chatto.api.v1.RoomService/ListPinnedMessages

Request to list a channel room’s current pinned messages.

FieldTypeDescription
room_idstringRequired channel room ID.
pagePageRequestDefaults to 50 results when absent or limit is zero. Maximum: 100.

Current pinned messages in one channel room.

FieldTypeDescription
pinned_messagesrepeated PinnedMessagePinned messages in newest-pin-first order.
pagePageInfoPage metadata.
latest_pin_markerstringOpaque marker for the latest pin fact observed for this room. The value remains stable when pins are removed so clients can detect new pins without comparing wall-clock timestamps. Clients must not interpret it.

Pins a current message. The caller must have message.pin and must be able to read the message. Repeating an existing pin is idempotent. Direct-message rooms are rejected.

POST /api/connect/chatto.api.v1.RoomService/CreatePinnedMessage

Request to pin a message in a channel room.

FieldTypeDescription
room_idstringRequired channel room ID.
message_event_idstringRequired canonical message event ID. Thread replies are supported.

Result of pinning a message.

FieldTypeDescription
pinned_messagePinnedMessageCurrent pinned-message resource. Repeating an existing pin returns it.

Removes a current pin. The caller must have message.pin. Removing a missing pin is idempotent. Direct-message rooms are rejected.

POST /api/connect/chatto.api.v1.RoomService/DeletePinnedMessage

Request to unpin a message from a channel room.

FieldTypeDescription
room_idstringRequired channel room ID.
message_event_idstringRequired canonical message event ID.

Result of unpinning a message.

FieldTypeDescription
deletedboolTrue when the message is not pinned after this call.

Refreshes the current user’s live-only typing indicator for a room or thread. Room membership is required; message posting permission is not. Send at most once every 2 seconds while typing. After posting a message, the next typing activity can send immediately. Stop sending when typing stops; receivers clear the indicator after 6 seconds without an event.

POST /api/connect/chatto.api.v1.RoomService/RefreshTypingIndicator

Request to refresh the current user’s live-only typing indicator.

FieldTypeDescription
room_idstringRequired. Room where the current user is typing.
thread_root_event_idstringEvent ID of the thread root when typing inside a thread.

Result of refreshing a typing indicator.

Returns one page of room timeline events, including related user data needed to render the page. Room membership is required. Reads also require message.read or message.read-interactions. The server returns only related thread roots for an interaction-scoped caller.

POST /api/connect/chatto.api.v1.RoomService/GetRoomEvents

Request for a page of room timeline events.

Omit the cursor to load the initial page. Set before to a previously returned start_cursor to page toward older events, or after to a previously returned end_cursor to page toward newer events.

FieldTypeDescription
room_idstringRequired. Room whose timeline should be loaded.
limitint32Maximum events. Values at or below zero use 50; values above 500 use 500.
cursor.beforestringReturn events older than this opaque cursor.
cursor.afterstringReturn events newer than this opaque cursor.

Response containing one room timeline page.

FieldTypeDescription
pageRoomTimelinePageLoaded timeline page.

Returns a room timeline window centered around a specific event. Use this to open a permalink, search result, or notification target in context. Returns NOT_FOUND when the anchor event is missing or not visible in the room timeline. Returns PERMISSION_DENIED when room membership or both read modes are missing, or when the anchor is in an unrelated thread.

POST /api/connect/chatto.api.v1.RoomService/GetRoomEventsAround

Request for room timeline events around a specific event.

Use this when a client needs to jump to a known event and render enough context around it.

FieldTypeDescription
room_idstringRequired. Room whose timeline should be loaded.
event_idstringRequired. Anchor event ID that should appear in the returned page.
limitint32Maximum events around the anchor. Values at or below zero use 50; values above 500 use 500.

Response containing a room timeline window around a specific event.

FieldTypeDescription
pageRoomTimelinePageLoaded timeline page.
target_indexint32Zero-based index of the anchor event within page.events.

Marks a room timeline as read through the supplied event. Room membership is required. Reads also require message.read or message.read-interactions. If no event is supplied, the server marks through the latest root event that the caller can read. Clients usually call this after the user has viewed the latest visible event in the room.

POST /api/connect/chatto.api.v1.RoomService/MarkRoomAsRead

Request to mark a room timeline as read.

FieldTypeDescription
room_idstringRequired. Room whose timeline should be marked read.
up_to_event_idstringHighest room event ID the current user has read. When set, the event must exist as a root event in the room timeline. Leave empty to mark through the room’s current latest root event.

Result of marking a room timeline as read.

Clients can use the previous timestamp to place a local New messages separator. Notification policy controls room Badge attention separately.

FieldTypeDescription
last_read_atgoogle.protobuf.TimestampNew room read timestamp stored for the current user.
previous_last_read_atgoogle.protobuf.TimestampPrevious room read timestamp, when one existed.

Removes a current channel room member with a required reason. Requires room.remove-member. Without suspension, ordinary join rules apply afterward. Universal rooms require a suspension. Direct-message rooms are excluded.

POST /api/connect/chatto.api.v1.RoomService/RemoveUser

Request to remove a user from a channel room for moderation.

FieldTypeDescription
room_idstringRequired. Channel room to remove the user from.
user_idstringRequired. Current room member to remove.
reasonstringRequired moderator-entered reason stored for audit.
suspension.suspension_expires_atgoogle.protobuf.TimestampFuture time after which the user may rejoin.
suspension.suspend_indefinitelyboolMust be true. The user cannot rejoin until the suspension is lifted.

Result of a moderated room removal.

Lifts an active channel room suspension. Requires room.remove-member. Calling this when no active suspension exists succeeds.

POST /api/connect/chatto.api.v1.RoomService/LiftSuspension

Request to lift a channel room suspension.

FieldTypeDescription
room_idstringRequired. Channel room containing the suspension.
user_idstringRequired. Suspended user.
reasonstringRequired moderator-entered reason stored for audit.

Result of lifting a room suspension.