MessageService
Chatto exposes this service below /api/connect.
Shared message and enum definitions are documented in Shared Types And Enums.
MessageService
Section titled “MessageService”Creates messages in room and thread timelines.
ListReactionUsers
Section titled “ListReactionUsers”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/ListReactionUsersInput: ListReactionUsersRequest
Section titled “Input: ListReactionUsersRequest”Request all users with one emoji reaction on a message. Echo IDs resolve to the original message. Users are ordered by user ID ascending.
| Field | Type | Description |
|---|---|---|
room_id | string | Room containing the message. |
message_event_id | string | Message or channel echo ID. |
emoji | string | Exact reaction name returned by the server, without surrounding colons. |
page | PageRequest | Defaults to 50 results. Maximum: 100. Zero uses the default. |
Result: ListReactionUsersResponse
Section titled “Result: ListReactionUsersResponse”Complete reaction membership is available by paging this collection.
| Field | Type | Description |
|---|---|---|
user_ids | repeated string | User IDs in this page. Use UserService.BatchGetUsers for profiles. |
page | PageInfo | Count and continuation for the matching reaction users. |
FetchLinkPreview
Section titled “FetchLinkPreview”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/FetchLinkPreviewInput: FetchLinkPreviewRequest
Section titled “Input: FetchLinkPreviewRequest”Request to fetch server-side link preview metadata for a URL.
| Field | Type | Description |
|---|---|---|
url | string | URL to preview. |
omit_preview_token | bool | Set for display-only reads to skip creation of a message-composer token. Older servers can ignore this field and still return a token. |
Result: FetchLinkPreviewResponse
Section titled “Result: FetchLinkPreviewResponse”Result of fetching link preview metadata.
| Field | Type | Description |
|---|---|---|
preview | LinkPreview | Preview metadata, or absent when the URL cannot be previewed. |
preview_token | string | Short-lived opaque token to pass to CreateMessage.link_preview_token when the user posts this preview. Empty when omit_preview_token is true. |
CreateMessage
Section titled “CreateMessage”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/CreateMessageInput: CreateMessageRequest
Section titled “Input: CreateMessageRequest”Request to create a message in a room or thread.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room where the message should be created. |
body | string | Message body text. Required unless attachment_asset_ids is non-empty. |
attachment_asset_ids | repeated string | Completed 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_id | string | Event ID of the thread root message when posting a thread reply. |
in_reply_to | string | Event ID this message replies to for attribution. |
also_send_to_channel | bool | True to also echo a thread reply into the main room timeline. |
link_preview_token | string | Short-lived token returned by FetchLinkPreview for the selected URL. The server resolves the token to cached, server-fetched metadata during post. |
create_thread | bool | True 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_descriptions | repeated MessageAttachmentDescriptionInput | Optional descriptions for assets in attachment_asset_ids. Asset IDs must be unique in this list. At most one description can target each asset. |
idempotency_key | optional string | Optional 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: CreateMessageResponse
Section titled “Result: CreateMessageResponse”Result of creating a message.
| Field | Type | Description |
|---|---|---|
message | Message | Renderable message created by the request. |
UpdateMessage
Section titled “UpdateMessage”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/UpdateMessageInput: UpdateMessageRequest
Section titled “Input: UpdateMessageRequest”Request to patch a message. update_mask selects fields to apply or reset. Fields outside the mask stay unchanged.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Event ID of the message to edit. |
body | optional string | New message body text. Select body in update_mask to change it. |
also_send_to_channel | optional bool | For thread replies, whether a channel echo should exist after saving. Select also_send_to_channel in update_mask to change it. |
update_mask | google.protobuf.FieldMask | Editable 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: UpdateMessageResponse
Section titled “Result: UpdateMessageResponse”Result of editing a message.
| Field | Type | Description |
|---|---|---|
message | Message | Renderable message after the edit. |
DeleteMessage
Section titled “DeleteMessage”Retracts a message. Authors can delete their own messages. Non-authors need message.manage.
POST /api/connect/chatto.api.v1.MessageService/DeleteMessageInput: DeleteMessageRequest
Section titled “Input: DeleteMessageRequest”Request to retract a message.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Event ID of the message to retract. |
Result: DeleteMessageResponse
Section titled “Result: DeleteMessageResponse”Result of retracting a message.
DeleteAttachment
Section titled “DeleteAttachment”Removes one attachment from the author’s own message.
POST /api/connect/chatto.api.v1.MessageService/DeleteAttachmentInput: DeleteAttachmentRequest
Section titled “Input: DeleteAttachmentRequest”Request to remove one attachment from a message.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Event ID of the message containing the attachment. |
attachment_id | string | Required. Attachment ID to remove from the message. |
Result: DeleteAttachmentResponse
Section titled “Result: DeleteAttachmentResponse”Result of removing one attachment from a message.
SetAttachmentDescription
Section titled “SetAttachmentDescription”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/SetAttachmentDescriptionInput: SetAttachmentDescriptionRequest
Section titled “Input: SetAttachmentDescriptionRequest”Request to set or clear one attachment description.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Message event containing the attachment, or its channel echo. |
attachment_id | string | Required. Attachment asset ID in the current message body. |
description | string | Replacement 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: SetAttachmentDescriptionResponse
Section titled “Result: SetAttachmentDescriptionResponse”Result of setting or clearing an attachment description.
| Field | Type | Description |
|---|---|---|
message | Message | Renderable message after the description change. |
DeleteLinkPreview
Section titled “DeleteLinkPreview”Removes the accepted link preview from the author’s own message.
POST /api/connect/chatto.api.v1.MessageService/DeleteLinkPreviewInput: DeleteLinkPreviewRequest
Section titled “Input: DeleteLinkPreviewRequest”Request to remove the accepted link preview from a message.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Event ID of the message containing the link preview. |
url | string | Required. URL of the link preview to remove. |
Result: DeleteLinkPreviewResponse
Section titled “Result: DeleteLinkPreviewResponse”Result of removing a link preview from a message.
GetMessage
Section titled “GetMessage”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/GetMessageInput: GetMessageRequest
Section titled “Input: GetMessageRequest”Request to read one visible message.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message. |
event_id | string | Required. Message event ID. |
Result: GetMessageResponse
Section titled “Result: GetMessageResponse”Response containing one renderable message.
| Field | Type | Description |
|---|---|---|
message | Message | Renderable message. |
BatchGetMessages
Section titled “BatchGetMessages”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/BatchGetMessagesInput: BatchGetMessagesRequest
Section titled “Input: BatchGetMessagesRequest”Request to read many visible messages in one room.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the messages. |
event_ids | repeated string | Required. Message event IDs. Missing, retracted, non-message, and wrong-room event IDs are omitted from the response. |
Result: BatchGetMessagesResponse
Section titled “Result: BatchGetMessagesResponse”Response containing renderable messages.
| Field | Type | Description |
|---|---|---|
messages | repeated Message | Renderable messages in first-seen request order. |
AddReaction
Section titled “AddReaction”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/AddReactionInput: AddReactionRequest
Section titled “Input: AddReactionRequest”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.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message event. |
message_event_id | string | Required. Event ID of the message being reacted to, or a channel echo of the message. |
emoji | string | Required. Supported reaction name, such as “heart” or “joy”. |
Result: AddReactionResponse
Section titled “Result: AddReactionResponse”Result of adding a reaction.
| Field | Type | Description |
|---|---|---|
added | bool | True when the reaction was newly added, false when it already existed. |
reaction | MessageReaction | Updated aggregate reaction state for this emoji. |
RemoveReaction
Section titled “RemoveReaction”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/RemoveReactionInput: RemoveReactionRequest
Section titled “Input: RemoveReactionRequest”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.
| Field | Type | Description |
|---|---|---|
room_id | string | Required. Room containing the message event. |
message_event_id | string | Required. Event ID of the message whose reaction should be removed, or a channel echo of the message. |
emoji | string | Required. Exact reaction name returned by the server, without surrounding colons. |
Result: RemoveReactionResponse
Section titled “Result: RemoveReactionResponse”Result of removing a reaction.
| Field | Type | Description |
|---|---|---|
removed | bool | True when the reaction was removed, false when it did not exist. |
reaction | MessageReaction | Updated aggregate reaction state for this emoji. Empty when no reactions for the emoji remain. |