docs: Improve documentation of attachment.proto, event_payload.proto and space.proto (#32284)

feat: Add app authorization support to space APIs
feat: Add accessory widget support for private messages

PiperOrigin-RevId: 845227338

Source-Link: googleapis/googleapis@1a9d00b

Source-Link: googleapis/googleapis-gen@ab1d025
Copy-Tag: eyJwIjoiZ29vZ2xlLWFwcHMtY2hhdC12MS8uT3dsQm90LnlhbWwiLCJoIjoiYWIxZDAyNTAwMjI0ZWI3ZWRhNDdkMjM0NjZlNDBkMjVjMTc2ZjIzYiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

google-apps-chat-v1/lib/google/apps/chat/v1/chat_service/client.rb

@@ -530,21 +530,34 @@ def create_message request, options = nil
 
             ##
             # Lists messages in a space that the caller is a member of, including
-            # messages from blocked members and spaces. If you list messages from a
+            # messages from blocked members and spaces. System messages, like those
+            # announcing new space members, aren't included. If you list messages from a
             # space with no messages, the response is an empty object. When using a
             # REST/HTTP interface, the response contains an empty JSON object, `{}`.
             # For an example, see
             # [List
             # messages](https://developers.google.com/workspace/chat/api/guides/v1/messages/list).
             #
-            # Requires [user
-            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
-            # with one of the following [authorization
-            # scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
+            # Supports the following types of
+            # [authentication](https://developers.google.com/workspace/chat/authenticate-authorize):
             #
-            #   - `https://www.googleapis.com/auth/chat.messages.readonly`
-            #   - `https://www.googleapis.com/auth/chat.messages`
-            #   - `https://www.googleapis.com/auth/chat.import` (import mode spaces only)
+            # - [App
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app)
+            # with [administrator
+            # approval](https://support.google.com/a?p=chat-app-auth) in
+            # [Developer Preview](https://developers.google.com/workspace/preview)
+            #  with the authorization scope:
+            #     - `https://www.googleapis.com/auth/chat.app.messages.readonly`. When
+            #     using this authentication scope, this method only returns public
+            #     messages in a space. It doesn't include private messages.
+            #
+            # - [User
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
+            # with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.messages.readonly`
+            #     - `https://www.googleapis.com/auth/chat.messages`
+            #     - `https://www.googleapis.com/auth/chat.import` (import mode spaces
+            #     only)
             #
             # @overload list_messages(request, options = nil)
             #   Pass arguments to `list_messages` via a request object, either of type
@@ -1057,8 +1070,18 @@ def get_membership request, options = nil
             #
             # - [App
             # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app)
-            # with the authorization scope:
-            #     - `https://www.googleapis.com/auth/chat.bot`
+            # with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.bot`: When using this
+            #     authorization scope, this method returns details about a message the
+            #     Chat app has access to, like direct messages and [slash
+            #     commands](https://developers.google.com/workspace/chat/slash-commands)
+            #     that invoke the Chat app.
+            #     - `https://www.googleapis.com/auth/chat.app.messages.readonly`
+            #     with [administrator
+            #     approval](https://support.google.com/a?p=chat-app-auth) (available in
+            #     [Developer Preview](https://developers.google.com/workspace/preview)).
+            #     When using this authentication scope,
+            #     this method returns details about a public message in a space.
             #
             # - [User
             # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
@@ -1751,7 +1774,9 @@ def list_spaces request, options = nil
 
             ##
             # Returns a list of spaces in a Google Workspace organization based on an
-            # administrator's search.
+            # administrator's search. In the request, set `use_admin_access` to `true`.
+            # For an example, see [Search for and manage
+            # spaces](https://developers.google.com/workspace/chat/search-manage-admin).
             #
             # Requires [user
             # authentication with administrator
@@ -1762,8 +1787,6 @@ def list_spaces request, options = nil
             #   - `https://www.googleapis.com/auth/chat.admin.spaces.readonly`
             #   - `https://www.googleapis.com/auth/chat.admin.spaces`
             #
-            # In the request, set `use_admin_access` to `true`.
-            #
             # @overload search_spaces(request, options = nil)
             #   Pass arguments to `search_spaces` via a request object, either of type
             #   {::Google::Apps::Chat::V1::SearchSpacesRequest} or an equivalent Hash.
@@ -2481,8 +2504,10 @@ def set_up_space request, options = nil
             #
             #     You can update the following fields for a space:
             #
-            #     `space_details`: Updates the space's description. Supports up to 150
-            #     characters.
+            #     `space_details`: Updates the space's description and guidelines. You must
+            #     pass both description and guidelines in the update request as
+            #     {::Google::Apps::Chat::V1::Space::SpaceDetails `SpaceDetails`}. If you only want to
+            #     update one of the fields, pass the existing value for the other field.
             #
             #     `display_name`: Only supports updating the display name for spaces where
             #     `spaceType` field is `SPACE`.
@@ -2526,8 +2551,7 @@ def set_up_space request, options = nil
             #     of a space.
             #     When updating permission settings, you can only specify
             #     `permissionSettings` field masks; you cannot update other field masks
-            #     at the same time. `permissionSettings` is not supported with
-            #     `useAdminAccess`.
+            #     at the same time.
             #     The supported field masks include:
             #
             #     - `permission_settings.manageMembersAndGroups`
@@ -4553,22 +4577,36 @@ def get_thread_read_state request, options = nil
             # Note: The `permissionSettings` field is not returned in the Space
             # object of the Space event data for this request.
             #
-            # Requires [user
-            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
-            # with an [authorization
+            # Supports the following types of
+            # [authentication](https://developers.google.com/workspace/chat/authenticate-authorize)
+            # with an
+            # [authorization
             # scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes)
             # appropriate for reading the requested data:
             #
-            #   - `https://www.googleapis.com/auth/chat.spaces.readonly`
-            #   - `https://www.googleapis.com/auth/chat.spaces`
-            #   - `https://www.googleapis.com/auth/chat.messages.readonly`
-            #   - `https://www.googleapis.com/auth/chat.messages`
-            #   - `https://www.googleapis.com/auth/chat.messages.reactions.readonly`
-            #   - `https://www.googleapis.com/auth/chat.messages.reactions`
-            #   - `https://www.googleapis.com/auth/chat.memberships.readonly`
-            #   - `https://www.googleapis.com/auth/chat.memberships`
+            # - [App
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app)
+            # with [administrator
+            # approval](https://support.google.com/a?p=chat-app-auth) in
+            # [Developer Preview](https://developers.google.com/workspace/preview)
+            #  with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.app.spaces`
+            #     - `https://www.googleapis.com/auth/chat.app.messages.readonly`
+            #     - `https://www.googleapis.com/auth/chat.app.memberships`
+            #
+            # - [User
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
+            # with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.spaces.readonly`
+            #     - `https://www.googleapis.com/auth/chat.spaces`
+            #     - `https://www.googleapis.com/auth/chat.messages.readonly`
+            #     - `https://www.googleapis.com/auth/chat.messages`
+            #     - `https://www.googleapis.com/auth/chat.messages.reactions.readonly`
+            #     - `https://www.googleapis.com/auth/chat.messages.reactions`
+            #     - `https://www.googleapis.com/auth/chat.memberships.readonly`
+            #     - `https://www.googleapis.com/auth/chat.memberships`
             #
-            # To get an event, the authenticated user must be a member of the space.
+            # To get an event, the authenticated caller must be a member of the space.
             #
             # For an example, see [Get details about an
             # event from a Google Chat
@@ -4667,22 +4705,36 @@ def get_space_event request, options = nil
             # removed during the requested period, the event payload contains an empty
             # `Membership` resource.
             #
-            # Requires [user
-            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
-            # with an [authorization
+            # Supports the following types of
+            # [authentication](https://developers.google.com/workspace/chat/authenticate-authorize)
+            # with an
+            # [authorization
             # scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes)
             # appropriate for reading the requested data:
             #
-            #   - `https://www.googleapis.com/auth/chat.spaces.readonly`
-            #   - `https://www.googleapis.com/auth/chat.spaces`
-            #   - `https://www.googleapis.com/auth/chat.messages.readonly`
-            #   - `https://www.googleapis.com/auth/chat.messages`
-            #   - `https://www.googleapis.com/auth/chat.messages.reactions.readonly`
-            #   - `https://www.googleapis.com/auth/chat.messages.reactions`
-            #   - `https://www.googleapis.com/auth/chat.memberships.readonly`
-            #   - `https://www.googleapis.com/auth/chat.memberships`
+            # - [App
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app)
+            # with [administrator
+            # approval](https://support.google.com/a?p=chat-app-auth) in
+            # [Developer Preview](https://developers.google.com/workspace/preview)
+            #  with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.app.spaces`
+            #     - `https://www.googleapis.com/auth/chat.app.messages.readonly`
+            #     - `https://www.googleapis.com/auth/chat.app.memberships`
+            #
+            # - [User
+            # authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
+            # with one of the following authorization scopes:
+            #     - `https://www.googleapis.com/auth/chat.spaces.readonly`
+            #     - `https://www.googleapis.com/auth/chat.spaces`
+            #     - `https://www.googleapis.com/auth/chat.messages.readonly`
+            #     - `https://www.googleapis.com/auth/chat.messages`
+            #     - `https://www.googleapis.com/auth/chat.messages.reactions.readonly`
+            #     - `https://www.googleapis.com/auth/chat.messages.reactions`
+            #     - `https://www.googleapis.com/auth/chat.memberships.readonly`
+            #     - `https://www.googleapis.com/auth/chat.memberships`
             #
-            # To list events, the authenticated user must be a member of the space.
+            # To list events, the authenticated caller must be a member of the space.
             #
             # For an example, see [List events from a Google Chat
             # space](https://developers.google.com/workspace/chat/list-space-events).

google-apps-chat-v1/lib/google/apps/chat/v1/chat_service/credentials.rb

@@ -33,6 +33,7 @@ class Credentials < ::Google::Auth::Credentials
               "https://www.googleapis.com/auth/chat.admin.spaces.readonly",
               "https://www.googleapis.com/auth/chat.app.delete",
               "https://www.googleapis.com/auth/chat.app.memberships",
+              "https://www.googleapis.com/auth/chat.app.messages.readonly",
               "https://www.googleapis.com/auth/chat.app.spaces",
               "https://www.googleapis.com/auth/chat.app.spaces.create",
               "https://www.googleapis.com/auth/chat.bot",