chat/v1/space.proto

// Copyright 2023 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";
import "google/chat/v1/history_state.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.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 = "SpaceProto";
option java_package = "com.google.chat.v1";
option php_namespace = "Google\\Apps\\Chat\\V1";
option ruby_package = "Google::Apps::Chat::V1";

// A space in Google Chat. Spaces are conversations between two or more users
// or 1:1 messages between a user and a Chat app.
message Space {
  option (google.api.resource) = {
    type: "chat.googleapis.com/Space"
    pattern: "spaces/{space}"
  };

  // Deprecated: Use `SpaceType` instead.
  enum Type {
    // Reserved.
    TYPE_UNSPECIFIED = 0;

    // Conversations between two or more humans.
    ROOM = 1;

    // 1:1 Direct Message between a human and a Chat app, where all messages are
    // flat. Note that this doesn't include direct messages between two humans.
    DM = 2;
  }

  // The type of space. Required when creating or updating a space. Output only
  // for other usage.
  enum SpaceType {
    // Reserved.
    SPACE_TYPE_UNSPECIFIED = 0;

    // A place where people send messages, share files, and collaborate.
    // A `SPACE` can include Chat apps.
    SPACE = 1;

    // Group conversations between 3 or more people.
    // A `GROUP_CHAT` can include Chat apps.
    GROUP_CHAT = 2;

    // 1:1 messages between two humans or a human and a Chat app.
    DIRECT_MESSAGE = 3;
  }

  // Specifies the type of threading state in the Chat space.
  enum SpaceThreadingState {
    // Reserved.
    SPACE_THREADING_STATE_UNSPECIFIED = 0;

    // Named spaces that support message threads. When users respond to a
    // message, they can reply in-thread, which keeps their response in the
    // context of the original message.
    THREADED_MESSAGES = 2;

    // Named spaces where the conversation is organized by topic. Topics and
    // their replies are grouped together.
    GROUPED_MESSAGES = 3;

    // Direct messages (DMs) between two people and group conversations between
    // 3 or more people.
    UNTHREADED_MESSAGES = 4;
  }

  // Details about the space including description and rules.
  message SpaceDetails {
    // Optional. A description of the space. For example, describe the space's
    // discussion topic, functional purpose, or participants.
    //
    // Supports up to 150 characters.
    string description = 1;

    // Optional. The space's rules, expectations, and etiquette.
    //
    // Supports up to 5,000 characters.
    string guidelines = 2;
  }

  // Resource name of the space.
  //
  // Format: `spaces/{space}`
  string name = 1;

  // Output only. Deprecated: Use `space_type` instead.
  // The type of a space.
  Type type = 2 [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];

  // The type of space. Required when creating a space or updating the space
  // type of a space. Output only for other usage.
  SpaceType space_type = 10;

  // Optional. Whether the space is a DM between a Chat app and a single
  // human.
  bool single_user_bot_dm = 4 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Deprecated: Use `spaceThreadingState` instead.
  // Whether messages are threaded in this space.
  bool threaded = 5
      [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];

  // The space's display name. Required when [creating a
  // space](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create).
  // If you receive the error message `ALREADY_EXISTS` when creating a space or
  // updating the `displayName`, try a different `displayName`. An
  // existing space within the Google Workspace organization might already use
  // this display name.
  //
  // For direct messages, this field might be empty.
  //
  // Supports up to 128 characters.
  string display_name = 3;

  // Immutable. Whether this space permits any Google Chat user as a member.
  // Input when creating a space in a Google Workspace organization. Omit this
  // field when creating spaces in the following conditions:
  //
  //   * The authenticated user uses a consumer account (unmanaged user
  //     account). By default, a space created by a consumer account permits any
  //     Google Chat user.
  //
  //   * The space is used to [import data to Google Chat]
  //     (https://developers.google.com/chat/api/guides/import-data-overview)
  //     because import mode spaces must only permit members from the same
  //     Google Workspace organization. However, as part of the [Google
  //     Workspace Developer Preview
  //     Program](https://developers.google.com/workspace/preview), import mode
  //     spaces can permit any Google Chat user so this field can then be set
  //     for import mode spaces.
  //
  // For existing spaces, this field is output only.
  bool external_user_allowed = 8 [(google.api.field_behavior) = IMMUTABLE];

  // Output only. The threading state in the Chat space.
  SpaceThreadingState space_threading_state = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Details about the space including description and rules.
  SpaceDetails space_details = 11;

  // The message history state for messages and threads in this space.
  HistoryState space_history_state = 13;

  // Optional. Whether this space is created in `Import Mode` as part of a data
  // migration into Google Workspace. While spaces are being imported, they
  // aren't visible to users until the import is complete.
  bool import_mode = 16 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Immutable. For spaces created in Chat, the time the space was
  // created. This field is output only, except when used in import mode spaces.
  //
  // For import mode spaces, set this field to the historical timestamp at which
  // the space was created in the source in order to preserve the original
  // creation time.
  //
  // Only populated in the output when `spaceType` is `GROUP_CHAT` or `SPACE`.
  google.protobuf.Timestamp create_time = 17 [
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.field_behavior) = OPTIONAL
  ];

  // Output only. Whether the Chat app was installed by a Google Workspace
  // administrator. Administrators can install a Chat app for their domain,
  // organizational unit, or a group of users.
  //
  // Administrators can only install Chat apps for direct messaging between
  // users and the app. To support admin install, your app must feature direct
  // messaging.
  bool admin_installed = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A request to create a named space.
message CreateSpaceRequest {
  // Required. The `displayName` and `spaceType` fields must be populated.  Only
  // `SpaceType.SPACE` is supported.
  //
  // If you receive the error message `ALREADY_EXISTS` when creating a space,
  // try a different `displayName`. An existing space within the Google
  // Workspace organization might already use this display name.
  //
  // The space `name` is assigned on the server so anything specified in this
  // field will be ignored.
  Space space = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. A unique identifier for this request.
  // A random UUID is recommended.
  // Specifying an existing request ID returns the space created with that ID
  // instead of creating a new space.
  // Specifying an existing request ID from the same Chat app with a different
  // authenticated user returns an error.
  string request_id = 2 [(google.api.field_behavior) = OPTIONAL];
}

// A request to list the spaces the caller is a member of.
message ListSpacesRequest {
  // Optional. The maximum number of spaces to return. The service might return
  // fewer than this value.
  //
  // If unspecified, at most 100 spaces are returned.
  //
  // The maximum value is 1000. If you use a value more than 1000, it's
  // automatically changed to 1000.
  //
  // Negative values return an `INVALID_ARGUMENT` error.
  int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous list spaces call.
  // Provide this parameter to retrieve the subsequent page.
  //
  // When paginating, the filter value should match the call that provided the
  // page token. Passing a different value may lead to unexpected results.
  string page_token = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A query filter.
  //
  // You can filter spaces by the space type
  // ([`space_type`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#spacetype)).
  //
  // To filter by space type, you must specify valid enum value, such as
  // `SPACE` or `GROUP_CHAT` (the `space_type` can't be
  // `SPACE_TYPE_UNSPECIFIED`). To query for multiple space types, use the `OR`
  // operator.
  //
  // For example, the following queries are valid:
  //
  // ```
  // space_type = "SPACE"
  // spaceType = "GROUP_CHAT" OR spaceType = "DIRECT_MESSAGE"
  // ```
  //
  // Invalid queries are rejected by the server with an `INVALID_ARGUMENT`
  // error.
  string filter = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The response for a list spaces request.
message ListSpacesResponse {
  // List of spaces in the requested (or first) page.
  repeated Space spaces = 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;
}

// A request to return a single space.
message GetSpaceRequest {
  // Required. Resource name of the space, in the form "spaces/*".
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// A request to get direct message space based on the user resource.
message FindDirectMessageRequest {
  // Required. Resource name of the user to find direct message with.
  //
  // Format: `users/{user}`, where `{user}` is either the `id` for the
  // [person](https://developers.google.com/people/api/rest/v1/people) from the
  // People API, or the `id` for the
  // [user](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users)
  // in the Directory API. For example, if the People API profile ID is
  // `123456789`, you can find a direct message with that person by using
  // `users/123456789` as the `name`. When [authenticated as a
  // user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
  // you can use the email as an alias for `{user}`. For example,
  // `users/example@gmail.com` where `[email protected]` is the email of the
  // Google Chat user.
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

// A request to update a single space.
message UpdateSpaceRequest {
  // Required. Space with fields to be updated. `Space.name` must be
  // populated in the form of `spaces/{space}`. Only fields
  // specified by `update_mask` are updated.
  Space space = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The updated field paths, comma separated if there are
  // multiple.
  //
  // Currently supported field paths:
  //
  // - `display_name` (Only supports changing the display name of a space with
  // the `SPACE` type, or when also including the `space_type` mask to change a
  // `GROUP_CHAT` space type to `SPACE`. Trying to update the display name of a
  // `GROUP_CHAT` or a `DIRECT_MESSAGE` space results in an invalid argument
  // error. If you receive the error message `ALREADY_EXISTS` when updating the
  // `displayName`, try a different `displayName`. An existing space within the
  // Google Workspace organization might already use this display name.)
  //
  // - `space_type` (Only supports changing a `GROUP_CHAT` space type to
  // `SPACE`. Include `display_name` together
  // with `space_type` in the update mask and ensure that the specified space
  // has a non-empty display name and the `SPACE` space type. Including the
  // `space_type` mask and the `SPACE` type in the specified space when updating
  // the display name is optional if the existing space already has the `SPACE`
  // type. Trying to update the space type in other ways results in an invalid
  // argument error).
  //
  // - `space_details`
  //
  // - `space_history_state` (Supports [turning history on or off for the
  // space](https://support.google.com/chat/answer/7664687) if [the organization
  // allows users to change their history
  // setting](https://support.google.com/a/answer/7664184).
  // Warning: mutually exclusive with all other field paths.)
  //
  // - Developer Preview: `access_settings.audience` (Supports changing the
  // [access setting](https://support.google.com/chat/answer/11971020) of a
  // space. If no audience is specified in the access setting, the space's
  // access setting is updated to restricted. Warning: mutually exclusive with
  // all other field paths.)
  google.protobuf.FieldMask update_mask = 2;
}

// Request for deleting a space.
message DeleteSpaceRequest {
  // Required. Resource name of the space to delete.
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// Request message for completing the import process for a space.
message CompleteImportSpaceRequest {
  // Required. Resource name of the import mode space.
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// Response message for completing the import process for a space.
message CompleteImportSpaceResponse {
  // The import mode space.
  Space space = 1;
}