chattolib/proto/chatto/api/v1/messages.proto

syntax = "proto3";

package chatto.api.v1;

import "buf/validate/validate.proto";
import "chatto/api/v1/link_previews.proto";
import "chatto/api/v1/message_types.proto";
import "chatto/api/v1/reactions.proto";

// Request to create a message in a room or thread.
message CreateMessageRequest {
  // Field 8 was `link_preview`, a client-provided metadata message used before
  // CreateMessage accepted only server-issued link preview tokens.
  reserved 8;
  reserved "link_preview";
  // Field 9 was `attachments`, inline attachment bytes accepted before
  // AssetUploadService moved uploads into a dedicated chunked API.
  reserved 9;
  reserved "attachments";
  // Field 7 was `mention_confirmation_token`, used by a server-enforced large
  // mention confirmation flow before role mention confirmation became a
  // client-only composer affordance.
  reserved 7;
  reserved "mention_confirmation_token";

  // Required. Room where the message should be created.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Message body text. Required unless attachment_asset_ids is non-empty.
  string body = 2;
  // 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.
  repeated string attachment_asset_ids = 3 [(buf.validate.field).repeated = {
    max_items: 10
    items: {
      string: {
        min_len: 1
        max_bytes: 15
      }
    }
  }];
  // Event ID of the thread root message when posting a thread reply.
  string thread_root_event_id = 4;
  // Event ID this message replies to for attribution.
  string in_reply_to = 5;
  // True to also echo a thread reply into the main room timeline.
  bool also_send_to_channel = 6;
  // Short-lived token returned by FetchLinkPreview for the selected URL. The
  // server resolves the token to cached, server-fetched metadata during post.
  string link_preview_token = 10;
  // True to establish the new root message as a thread immediately. Requires
  // both message.post and message.post-in-thread. Channel rooms only; cannot
  // be combined with thread_root_event_id.
  bool create_thread = 11;
}

// Result of creating a message.
message CreateMessageResponse {
  // Field 2 was `mention_confirmation`, used by a server-enforced large
  // mention confirmation flow before role mention confirmation became a
  // client-only composer affordance.
  reserved 2;
  reserved "mention_confirmation";
  // Field 3 was `includes`, used before create responses were narrowed to the
  // generated message.
  reserved 3;
  reserved "includes";

  // Renderable message created by the request.
  Message message = 1;
}

// Request to patch a message.
message UpdateMessageRequest {
  // Required. Room containing the message.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Event ID of the message to edit.
  string event_id = 2 [(buf.validate.field).string.min_len = 1];
  // New message body text. Omit to preserve the current body.
  optional string body = 3 [(buf.validate.field).string.max_len = 10000];
  // For thread replies, whether a channel echo should exist after saving.
  // Omit to preserve the current echo state.
  optional bool also_send_to_channel = 4;
}

// Result of editing a message.
message UpdateMessageResponse {
  reserved 1;
  reserved "updated";

  // Field 3 was `includes`, used before update responses were narrowed to the
  // edited message.
  reserved 3;
  reserved "includes";

  // Renderable message after the edit.
  Message message = 2;
}

// Request to retract a message.
message DeleteMessageRequest {
  // Required. Room containing the message.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Event ID of the message to retract.
  string event_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Result of retracting a message.
message DeleteMessageResponse {
  // True when the delete/retract request was accepted.
  bool deleted = 1;
}

// Request to remove one attachment from a message.
message DeleteAttachmentRequest {
  // Required. Room containing the message.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Event ID of the message containing the attachment.
  string event_id = 2 [(buf.validate.field).string.min_len = 1];
  // Required. Attachment ID to remove from the message.
  string attachment_id = 3 [(buf.validate.field).string.min_len = 1];
}

// Result of removing one attachment from a message.
message DeleteAttachmentResponse {
  // True when the attachment removal was accepted.
  bool deleted = 1;
}

// Request to remove the accepted link preview from a message.
message DeleteLinkPreviewRequest {
  // Required. Room containing the message.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Event ID of the message containing the link preview.
  string event_id = 2 [(buf.validate.field).string.min_len = 1];
  // Required. URL of the link preview to remove.
  string url = 3 [(buf.validate.field).string.min_len = 1];
}

// Result of removing a link preview from a message.
message DeleteLinkPreviewResponse {
  // True when the link preview removal was accepted.
  bool deleted = 1;
}

// Request to read one visible message.
message GetMessageRequest {
  // Field 3 was `thumbnail`, used before custom attachment URL hydration moved
  // to AssetService.
  reserved 3;
  reserved "thumbnail";

  // Required. Room containing the message.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Message event ID.
  string event_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Response containing one renderable message.
message GetMessageResponse {
  // Field 2 was `includes`, used before message read responses were narrowed
  // to messages.
  reserved 2;
  reserved "includes";

  // Renderable message.
  Message message = 1;
}

// Request to read many visible messages in one room.
message BatchGetMessagesRequest {
  // Field 3 was `thumbnail`, used before custom attachment URL hydration moved
  // to AssetService.
  reserved 3;
  reserved "thumbnail";

  // Required. Room containing the messages.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. Message event IDs. Missing, retracted, non-message, and
  // wrong-room event IDs are omitted from the response.
  repeated string event_ids = 2 [(buf.validate.field).repeated = {
    min_items: 1
    max_items: 100
    items: {
      string: {min_len: 1}
    }
  }];
}

// Response containing renderable messages.
message BatchGetMessagesResponse {
  // Field 2 was `includes`, used before message read responses were narrowed
  // to messages.
  reserved 2;
  reserved "includes";

  // Renderable messages in first-seen request order.
  repeated Message messages = 1;
}

// Creates messages in room and thread timelines.
service MessageService {
  // Fetches and caches metadata for a composer 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.
  rpc FetchLinkPreview(FetchLinkPreviewRequest) returns (FetchLinkPreviewResponse);
  // Creates a message for the current user. The user must be a room member and
  // must have message.post for room messages or message.post-in-thread for
  // thread replies. 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.
  rpc CreateMessage(CreateMessageRequest) returns (CreateMessageResponse);
  // Edits a message body. Authors can edit their own messages within the edit
  // window. Non-authors need message.manage and cannot change channel echo
  // state. Disabled rooms reject creation of a new channel echo while allowing
  // an existing echo to be removed. Room membership is also required.
  // Channel-room edits require message.read or a matching thread relationship
  // with message.read-interactions. DM membership authorizes the DM read.
  rpc UpdateMessage(UpdateMessageRequest) returns (UpdateMessageResponse);
  // Retracts a message. Authors can delete their own messages. Non-authors need
  // message.manage.
  rpc DeleteMessage(DeleteMessageRequest) returns (DeleteMessageResponse);
  // Removes one attachment from the author's own message.
  rpc DeleteAttachment(DeleteAttachmentRequest) returns (DeleteAttachmentResponse);
  // Removes the accepted link preview from the author's own message.
  rpc DeleteLinkPreview(DeleteLinkPreviewRequest) returns (DeleteLinkPreviewResponse);
  // Reads one renderable message, including current body, attachment metadata,
  // link preview, reactions, thread metadata, and pin state. Authentication
  // and room membership are required. Channel-room reads also require
  // message.read or a matching thread relationship with
  // message.read-interactions. DM membership authorizes DM reads. Returns
  // NOT_FOUND when the event does not exist, is not a message, has been
  // retracted, or belongs to a different room.
  rpc GetMessage(GetMessageRequest) returns (GetMessageResponse);
  // Reads many renderable messages and their current pin state in one room.
  // Authentication and room membership are required. Channel-room reads also
  // require message.read or a matching thread relationship with
  // message.read-interactions. DM membership authorizes DM reads. 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.
  rpc BatchGetMessages(BatchGetMessagesRequest) returns (BatchGetMessagesResponse);
  // Adds a reaction to a message. The user must be a room member and have
  // message.react. Channel-room reactions also require message.read or a
  // matching thread relationship with message.read-interactions. DM membership
  // authorizes the DM read.
  rpc AddReaction(AddReactionRequest) returns (AddReactionResponse);
  // Removes a reaction from a message. The user must be a room member and have
  // message.react. Channel-room reactions also require message.read or a
  // matching thread relationship with message.read-interactions. DM membership
  // authorizes the DM read.
  rpc RemoveReaction(RemoveReactionRequest) returns (RemoveReactionResponse);
}