// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.chat.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option csharp_namespace = "Google.Apps.Chat.V1";
option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
option java_multiple_files = true;
option java_outer_classname = "MessagePinProto";
option java_package = "com.google.chat.v1";
option objc_class_prefix = "DYNAPIProto";
option php_namespace = "Google\\Apps\\Chat\\V1";
option ruby_package = "Google::Apps::Chat::V1";

// A pin on a Chat message. For more information see [Pin a
// message](https://support.google.com/chat?p=chat-board-hc).
message MessagePin {
  option (google.api.resource) = {
    type: "chat.googleapis.com/MessagePin"
    pattern: "spaces/{space}/messagePins/{message_pin}"
    plural: "messagePins"
    singular: "messagePin"
  };

  // Identifier. The resource name of the message pin.
  // Format: `spaces/{space}/messagePins/{message_pin}`
  // The resource ID component matches the resource ID component of the
  // message. For example, a message with `spaces/AAA/messages/bbb.ccc`
  // corresponds to the message pin with the resource name
  // `spaces/AAA/messagePins/bbb.ccc`.
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. Immutable. The resource name of the message that is pinned.
  // Format: `spaces/{space}/messages/{message}`
  string message = 2 [
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Message" }
  ];
}

// Request message for listing message pins.
message ListMessagePinsRequest {
  // Required. The parent space which owns the collection of pinned items
  // Format: `spaces/{space}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "chat.googleapis.com/MessagePin"
    }
  ];

  // Optional. The maximum number of message pins returned. The service might
  // return fewer messages than this value. The maximum value is 100. If you use
  // a value more than 100, it's automatically changed to 100. If unspecified,
  // at most 100 message pins will be returned. Negative values return an
  // `INVALID_ARGUMENT` error.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous list message pins call.
  // Provide this parameter to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided should match the call that
  // provided the page token. Passing different values to the other parameters
  // might lead to unexpected results.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for listing message pins.
message ListMessagePinsResponse {
  // The pinned messages from the specified space.
  repeated MessagePin message_pins = 1;

  // You can send a token as `pageToken` to retrieve the next page of
  // results. If empty, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for creating a message pin.
message CreateMessagePinRequest {
  // Required. The parent space in which to create the message pin.
  // Format: spaces/{space}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];

  // Required. The MessagePin to create.
  MessagePin message_pin = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for deleting a message pin.
message DeleteMessagePinRequest {
  // Required. The resource name of the message pin to remove.
  // Format: spaces/{space}/messagePins/{message_pin}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/MessagePin" }
  ];
}