docs: update Chat API comments

Google APIs · copybara-github · commit 6cac6e4f2b8f · 2024-05-13T13:51:25.000-07:00
PiperOrigin-RevId: 633320855
diff --git a/google/chat/v1/action_status.proto b/google/chat/v1/action_status.proto
@@ -23,6 +23,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "ActionStatusProto";
 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";
 
diff --git a/google/chat/v1/annotation.proto b/google/chat/v1/annotation.proto
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.chat.v1;
 
+import "google/api/resource.proto";
 import "google/chat/v1/attachment.proto";
 import "google/chat/v1/user.proto";
 
@@ -24,6 +25,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "AnnotationProto";
 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";
 
diff --git a/google/chat/v1/attachment.proto b/google/chat/v1/attachment.proto
@@ -24,6 +24,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "AttachmentProto";
 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";
 
diff --git a/google/chat/v1/chat_service.proto b/google/chat/v1/chat_service.proto
@@ -33,6 +33,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "ChatServiceProto";
 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";
 
@@ -59,7 +60,8 @@ service ChatService {
       "https://www.googleapis.com/auth/chat.users.readstate,"
       "https://www.googleapis.com/auth/chat.users.readstate.readonly";
 
-  // Creates a message in a Google Chat space. For an example, see [Send a
+  // Creates a message in a Google Chat space. The maximum message size,
+  // including text and cards, is 32,000 bytes. For an example, see [Send a
   // message](https://developers.google.com/workspace/chat/create-messages).
   //
   // Calling this method requires
@@ -250,6 +252,7 @@ service ChatService {
   //
   // Lists spaces visible to the caller or authenticated user. Group chats
   // and DMs aren't listed until the first message is sent.
+  //
   rpc ListSpaces(ListSpacesRequest) returns (ListSpacesResponse) {
     option (google.api.http) = {
       get: "/v1/spaces"
@@ -300,17 +303,17 @@ service ChatService {
   // members](https://developers.google.com/workspace/chat/set-up-spaces).
   //
   // To specify the human members to add, add memberships with the appropriate
-  // `member.name` in the `SetUpSpaceRequest`. To add a human user, use
-  // `users/{user}`, where `{user}` can be the email address for the user. For
-  // users in the same Workspace organization `{user}` can also be the `id` for
-  // the person from the People API, or the `id` for the user in the Directory
-  // API. For example, if the People API Person profile ID for
-  // `user@example.com` is `123456789`, you can add the user to the space by
-  // setting the `membership.member.name` to `users/user@example.com` or
-  // `users/123456789`.
-  //
-  // For a space or group chat, if the caller blocks or is blocked by some
-  // members, then those members aren't added to the created space.
+  // `membership.member.name`. To add a human user, use `users/{user}`, where
+  // `{user}` can be the email address for the user. For users in the same
+  // Workspace organization `{user}` can also be the `id` for the person from
+  // the People API, or the `id` for the user in the Directory API. For example,
+  // if the People API Person profile ID for `user@example.com` is `123456789`,
+  // you can add the user to the space by setting the `membership.member.name`
+  // to `users/user@example.com` or `users/123456789`.
+  //
+  // For a named space or group chat, if the caller blocks, or is blocked
+  // by some members, or doesn't have permission to add some members, then
+  // those members aren't added to the created space.
   //
   // To create a direct message (DM) between the calling user and another human
   // user, specify exactly one membership to represent the human user. If
@@ -423,8 +426,8 @@ service ChatService {
   // directly to the specified space. Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   //
-  // To specify the member to add, set the `membership.member.name` in the
-  // `CreateMembershipRequest`:
+  // To specify the member to add, set the `membership.member.name` for the
+  // human or app member.
   //
   // - To add the calling app to a space or a direct message between two human
   //   users, use `users/app`. Unable to add other
@@ -445,8 +448,11 @@ service ChatService {
     option (google.api.method_signature) = "parent,membership";
   }
 
-  // Updates a membership. Requires [user
-  // authentication](https://developers.google.com/chat/api/guides/auth/users).
+  // Updates a membership. For an example, see [Update a user's membership in
+  // a space](https://developers.google.com/workspace/chat/update-members).
+  //
+  // Requires [user
+  // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   rpc UpdateMembership(UpdateMembershipRequest) returns (Membership) {
     option (google.api.http) = {
       patch: "/v1/{membership.name=spaces/*/members/*}"
@@ -508,7 +514,9 @@ service ChatService {
   }
 
   // Returns details about a user's read state within a space, used to identify
-  // read and unread messages.
+  // read and unread messages. For an example, see [Get details about a user's
+  // space read
+  // state](https://developers.google.com/workspace/chat/get-space-read-state).
   //
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
@@ -520,7 +528,8 @@ service ChatService {
   }
 
   // Updates a user's read state within a space, used to identify read and
-  // unread messages.
+  // unread messages. For an example, see [Update a user's space read
+  // state](https://developers.google.com/workspace/chat/update-space-read-state).
   //
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
@@ -534,7 +543,9 @@ service ChatService {
   }
 
   // Returns details about a user's read state within a thread, used to identify
-  // read and unread messages.
+  // read and unread messages. For an example, see [Get details about a user's
+  // thread read
+  // state](https://developers.google.com/workspace/chat/get-thread-read-state).
   //
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
diff --git a/google/chat/v1/chat_v1.yaml b/google/chat/v1/chat_v1.yaml
@@ -95,6 +95,16 @@ authentication:
         https://www.googleapis.com/auth/chat.bot,
         https://www.googleapis.com/auth/chat.spaces,
         https://www.googleapis.com/auth/chat.spaces.readonly
+  - selector: google.chat.v1.ChatService.GetSpaceReadState
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/chat.users.readstate,
+        https://www.googleapis.com/auth/chat.users.readstate.readonly
+  - selector: google.chat.v1.ChatService.GetThreadReadState
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/chat.users.readstate,
+        https://www.googleapis.com/auth/chat.users.readstate.readonly
   - selector: google.chat.v1.ChatService.ListMemberships
     oauth:
       canonical_scopes: |-
@@ -126,6 +136,11 @@ authentication:
       canonical_scopes: |-
         https://www.googleapis.com/auth/chat.spaces,
         https://www.googleapis.com/auth/chat.spaces.create
+  - selector: google.chat.v1.ChatService.UpdateMembership
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/chat.import,
+        https://www.googleapis.com/auth/chat.memberships
   - selector: google.chat.v1.ChatService.UpdateMessage
     oauth:
       canonical_scopes: |-
@@ -137,6 +152,10 @@ authentication:
       canonical_scopes: |-
         https://www.googleapis.com/auth/chat.import,
         https://www.googleapis.com/auth/chat.spaces
+  - selector: google.chat.v1.ChatService.UpdateSpaceReadState
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/chat.users.readstate
   - selector: google.chat.v1.ChatService.UploadAttachment
     oauth:
       canonical_scopes: |-
diff --git a/google/chat/v1/contextual_addon.proto b/google/chat/v1/contextual_addon.proto
@@ -23,6 +23,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "ContextualAddOnProto";
 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";
 
diff --git a/google/chat/v1/deletion_metadata.proto b/google/chat/v1/deletion_metadata.proto
@@ -21,6 +21,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "DeletionMetadataProto";
 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";
 
diff --git a/google/chat/v1/group.proto b/google/chat/v1/group.proto
@@ -21,6 +21,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "GroupProto";
 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";
 
diff --git a/google/chat/v1/history_state.proto b/google/chat/v1/history_state.proto
@@ -21,6 +21,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "HistoryStateProto";
 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";
 
diff --git a/google/chat/v1/matched_url.proto b/google/chat/v1/matched_url.proto
@@ -23,6 +23,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "MatchedUrlProto";
 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";
 
diff --git a/google/chat/v1/membership.proto b/google/chat/v1/membership.proto
@@ -28,6 +28,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "MembershipProto";
 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";
 
@@ -105,8 +106,8 @@ message Membership {
     User member = 3;
 
     // The Google Group the membership corresponds to.
-    // Only supports read operations. Other operations, like creating or
-    // updating a membership, aren't currently supported.
+    // Only supports read operations. Other operations, like
+    // creating or updating a membership, aren't currently supported.
     Group group_member = 5;
   }
 
@@ -275,8 +276,9 @@ message ListMembershipsResponse {
 message GetMembershipRequest {
   // Required. Resource name of the membership to retrieve.
   //
-  // To get the app's own membership, you can optionally use
-  // `spaces/{space}/members/app`.
+  // To get the app's own membership [by using user
+  // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
+  // you can optionally use `spaces/{space}/members/app`.
   //
   // Format: `spaces/{space}/members/{member}` or `spaces/{space}/members/app`
   //
diff --git a/google/chat/v1/message.proto b/google/chat/v1/message.proto
@@ -37,6 +37,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "MessageProto";
 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";
 
diff --git a/google/chat/v1/reaction.proto b/google/chat/v1/reaction.proto
@@ -25,6 +25,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "ReactionProto";
 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";
 
@@ -61,8 +62,8 @@ message Emoji {
 
 // Represents a custom emoji.
 message CustomEmoji {
-  // Unique key for the custom emoji resource.
-  string uid = 1;
+  // Output only. Unique key for the custom emoji resource.
+  string uid = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The number of people who reacted to a message with a specific emoji.
diff --git a/google/chat/v1/slash_command.proto b/google/chat/v1/slash_command.proto
@@ -21,6 +21,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "SlashCommandProto";
 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";
 
diff --git a/google/chat/v1/space.proto b/google/chat/v1/space.proto
@@ -27,6 +27,7 @@ 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 objc_class_prefix = "DYNAPIProto";
 option php_namespace = "Google\\Apps\\Chat\\V1";
 option ruby_package = "Google::Apps::Chat::V1";
 
@@ -184,13 +185,12 @@ message Space {
     (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.
+  // Output only. For direct message (DM) spaces with a Chat app, whether the
+  // space was created by a Google Workspace administrator. Administrators can
+  // install and set up a direct message with a Chat app on behalf of users in
+  // their organization.
   //
-  // Administrators can only install Chat apps for direct messaging between
-  // users and the app. To support admin install, your app must feature direct
-  // messaging.
+  // To support admin install, your Chat app must feature direct messaging.
   bool admin_installed = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
diff --git a/google/chat/v1/space_read_state.proto b/google/chat/v1/space_read_state.proto
@@ -26,6 +26,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "SpaceReadStateProto";
 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";
 
diff --git a/google/chat/v1/space_setup.proto b/google/chat/v1/space_setup.proto
@@ -25,6 +25,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "SpaceSetupProto";
 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";
 
@@ -68,14 +69,14 @@ message SetUpSpaceRequest {
   //
   // The set currently allows up to 20 memberships (in addition to the caller).
   //
-  // The `Membership.member` field must contain a `user` with `name` populated
-  // (format: `users/{user}`) and `type` set to `User.Type.HUMAN`. You can only
-  // add human users when setting up a space (adding Chat apps is only supported
-  // for direct message setup with the calling app). You can also add members
-  // using the user's email as an alias for {user}. For example, the `user.name`
-  // can be `users/example@gmail.com`." To invite Gmail users or users from
-  // external Google Workspace domains, user's email must be used for
-  // `{user}`.
+  // For human membership, the `Membership.member` field must contain a `user`
+  // with `name` populated (format: `users/{user}`) and `type` set to
+  // `User.Type.HUMAN`. You can only add human users when setting up a space
+  // (adding Chat apps is only supported for direct message setup with the
+  // calling app). You can also add members using the user's email as an alias
+  // for {user}. For example, the `user.name` can be `users/example@gmail.com`.
+  // To invite Gmail users or users from external Google Workspace domains,
+  // user's email must be used for `{user}`.
   //
   // Optional when setting `Space.spaceType` to `SPACE`.
   //
diff --git a/google/chat/v1/thread_read_state.proto b/google/chat/v1/thread_read_state.proto
@@ -25,6 +25,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "ThreadReadStateProto";
 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";
 
diff --git a/google/chat/v1/user.proto b/google/chat/v1/user.proto
@@ -24,6 +24,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "UserProto";
 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";
 
diff --git a/google/chat/v1/widgets.proto b/google/chat/v1/widgets.proto
@@ -21,6 +21,7 @@ option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
 option java_multiple_files = true;
 option java_outer_classname = "WidgetsProto";
 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";
 
