Skip to content
Chatto v0.5.0

MessageService

Chatto exposes this service below /api/connect.

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

Creates messages in room and thread timelines.

Lists all users with the requested reaction. Requires room membership and permission to read the message. A missing reaction returns an empty page; a missing or hidden message returns NOT_FOUND or PERMISSION_DENIED.

POST /api/connect/chatto.api.v1.MessageService/ListReactionUsers

Request all users with one emoji reaction on a message. Echo IDs resolve to the original message. Users are ordered by user ID ascending.

FieldTypeDescription
room_idstringRoom containing the message.
message_event_idstringMessage or channel echo ID.
emojistringExact reaction name returned by the server, without surrounding colons.
pagePageRequestDefaults to 50 results. Maximum: 100. Zero uses the default.

Complete reaction membership is available by paging this collection.

FieldTypeDescription
user_idsrepeated stringUser IDs in this page. Use UserService.BatchGetUsers for profiles.
pagePageInfoCount and continuation for the matching reaction users.

Fetches and caches metadata for a URL. Authentication is required to avoid exposing the preview fetcher as an unauthenticated network proxy. Successful responses include a short-lived token accepted by CreateMessage, unless omit_preview_token is set for a display-only read.

POST /api/connect/chatto.api.v1.MessageService/FetchLinkPreview

Request to fetch server-side link preview metadata for a URL.

FieldTypeDescription
urlstringURL to preview.
omit_preview_tokenboolSet for display-only reads to skip creation of a message-composer token. Older servers can ignore this field and still return a token.

Result of fetching link preview metadata.

FieldTypeDescription
previewLinkPreviewPreview metadata, or absent when the URL cannot be previewed.
preview_tokenstringShort-lived opaque token to pass to CreateMessage.link_preview_token when the user posts this preview. Empty when omit_preview_token is true.

Creates a message for the current user. The user must be a room member and must have message.post for room messages. Thread replies require read access and either message.post, message.post-in-thread, or message.post-in-interactions with an existing interaction relationship. Echoing a thread reply also requires message.echo and message.post. The room’s Threading Mode may automatically establish a root thread or reject a thread placement that the mode does not allow.

POST /api/connect/chatto.api.v1.MessageService/CreateMessage

Request to create a message in a room or thread.

FieldTypeDescription
room_idstringRequired. Room where the message should be created.
bodystringMessage body text. Required unless attachment_asset_ids is non-empty.
attachment_asset_idsrepeated stringCompleted room-scoped asset IDs uploaded by the caller and not yet attached to a message. The server attaches them exclusively and atomically to this message. At most 10 IDs may be supplied.
thread_root_event_idstringEvent ID of the thread root message when posting a thread reply.
in_reply_tostringEvent ID this message replies to for attribution.
also_send_to_channelboolTrue to also echo a thread reply into the main room timeline.
link_preview_tokenstringShort-lived token returned by FetchLinkPreview for the selected URL. The server resolves the token to cached, server-fetched metadata during post.
create_threadboolTrue to establish the new root message as a thread immediately. Requires message.post (which includes thread posting). Cannot be combined with thread_root_event_id.
attachment_descriptionsrepeated MessageAttachmentDescriptionInputOptional descriptions for assets in attachment_asset_ids. Asset IDs must be unique in this list. At most one description can target each asset.
idempotency_keyoptional stringOptional caller-generated UUID for this send. Reuse it with the same room and request when a response is lost. For 30 minutes after first acceptance, an exact retry returns the same message ID; changed arguments are rejected. Retries do not extend this period. After expiry, the key can be used again. Omit the key for ordinary posting without duplicate protection.

Result of creating a message.

FieldTypeDescription
messageMessageRenderable message created by the request.

Edits a message body. Authors can edit their own messages within the edit window. Effective message.manage permits edits at any time and removal of another author’s channel echo. Only the author can enable an echo, which also requires message.echo and message.post. Omit unchanged echo state. Disabled rooms reject creation of a new channel echo while allowing an existing echo to be removed. Room membership is also required. Edits require message.read or a matching thread relationship with message.read-interactions.

POST /api/connect/chatto.api.v1.MessageService/UpdateMessage

Request to patch a message. update_mask selects fields to apply or reset. Fields outside the mask stay unchanged.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Event ID of the message to edit.
bodyoptional stringNew message body text. Select body in update_mask to change it.
also_send_to_channeloptional boolFor thread replies, whether a channel echo should exist after saving. Select also_send_to_channel in update_mask to change it.
update_maskgoogle.protobuf.FieldMaskEditable fields to apply or reset: body, also_send_to_channel. 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.

Result of editing a message.

FieldTypeDescription
messageMessageRenderable message after the edit.

Retracts a message. Authors can delete their own messages. Non-authors need message.manage.

POST /api/connect/chatto.api.v1.MessageService/DeleteMessage

Request to retract a message.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Event ID of the message to retract.

Result of retracting a message.

Removes one attachment from the author’s own message.

POST /api/connect/chatto.api.v1.MessageService/DeleteAttachment

Request to remove one attachment from a message.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Event ID of the message containing the attachment.
attachment_idstringRequired. Attachment ID to remove from the message.

Result of removing one attachment from a message.

Sets or clears one attachment description. Authors can change descriptions within the message edit window. Effective message.manage permits changes at any time and to other users’ messages. Room membership and message read access are required.

POST /api/connect/chatto.api.v1.MessageService/SetAttachmentDescription

Request to set or clear one attachment description.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Message event containing the attachment, or its channel echo.
attachment_idstringRequired. Attachment asset ID in the current message body.
descriptionstringReplacement description with at most 1,000 Unicode characters. Trim outer whitespace before sending. Chatto also trims outer whitespace and preserves internal line breaks. An empty result clears the description.

Result of setting or clearing an attachment description.

FieldTypeDescription
messageMessageRenderable message after the description change.

Removes the accepted link preview from the author’s own message.

POST /api/connect/chatto.api.v1.MessageService/DeleteLinkPreview

Request to remove the accepted link preview from a message.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Event ID of the message containing the link preview.
urlstringRequired. URL of the link preview to remove.

Result of removing a link preview from a message.

Reads one renderable message, including current body, attachment metadata, link preview, reactions, thread metadata, and pin state. Authentication and room membership are required. Reads also require message.read or a matching thread relationship with message.read-interactions. Returns NOT_FOUND when the event does not exist, is not a message, has been retracted, or belongs to a different room.

POST /api/connect/chatto.api.v1.MessageService/GetMessage

Request to read one visible message.

FieldTypeDescription
room_idstringRequired. Room containing the message.
event_idstringRequired. Message event ID.

Response containing one renderable message.

FieldTypeDescription
messageMessageRenderable message.

Reads many renderable messages and their current pin state in one room. Authentication and room membership are required. Reads also require message.read or a matching thread relationship with message.read-interactions. Missing, retracted, non-message, wrong-room, and inaccessible event IDs are omitted. Results preserve first-seen request order, and repeated event IDs are de-duplicated.

POST /api/connect/chatto.api.v1.MessageService/BatchGetMessages

Request to read many visible messages in one room.

FieldTypeDescription
room_idstringRequired. Room containing the messages.
event_idsrepeated stringRequired. Message event IDs. Missing, retracted, non-message, and wrong-room event IDs are omitted from the response.

Response containing renderable messages.

FieldTypeDescription
messagesrepeated MessageRenderable messages in first-seen request order.

Adds a reaction to a message. The user must be a room member and have message.react. Reactions also require message.read or a matching thread relationship with message.read-interactions.

POST /api/connect/chatto.api.v1.MessageService/AddReaction

Request to add the current user’s reaction to a message.

When message_event_id names a channel echo of a thread reply, the server treats it as an alias for the original thread reply and stores the reaction on that original event. The server returns RESOURCE_EXHAUSTED when the current user already has 20 distinct emoji reactions on the canonical message; adding an emoji that already exists remains an idempotent success. Names contain 1–128 ASCII letters, digits, underscores, plus signs, or hyphens, without surrounding colons. Known emoji also accept valid Slack-style skin-tone suffixes, such as thumbsup::skin-tone-4. The full name must fit in 128 characters. Names are case-sensitive, must be in the bundled emoji catalogue, and are stored unchanged. Unknown names return INVALID_ARGUMENT. Unicode glyphs are not accepted; clients must send a supported shortcode name.

FieldTypeDescription
room_idstringRequired. Room containing the message event.
message_event_idstringRequired. Event ID of the message being reacted to, or a channel echo of the message.
emojistringRequired. Supported reaction name, such as “heart” or “joy”.

Result of adding a reaction.

FieldTypeDescription
addedboolTrue when the reaction was newly added, false when it already existed.
reactionMessageReactionUpdated aggregate reaction state for this emoji.

Removes a reaction from a message. The user must be a room member and have message.react. Reactions also require message.read or a matching thread relationship with message.read-interactions.

POST /api/connect/chatto.api.v1.MessageService/RemoveReaction

Request to remove the current user’s reaction from a message.

When message_event_id names a channel echo of a thread reply, the server treats it as an alias for the original thread reply and removes the reaction from that original event.

FieldTypeDescription
room_idstringRequired. Room containing the message event.
message_event_idstringRequired. Event ID of the message whose reaction should be removed, or a channel echo of the message.
emojistringRequired. Exact reaction name returned by the server, without surrounding colons.

Result of removing a reaction.

FieldTypeDescription
removedboolTrue when the reaction was removed, false when it did not exist.
reactionMessageReactionUpdated aggregate reaction state for this emoji. Empty when no reactions for the emoji remain.