@google-apps/chat 0.28.0 → 0.29.0

package/build/protos/google/chat/v1/chat_service.proto

@@ -342,6 +342,41 @@ service ChatService {
     option (google.api.method_signature) = "name";
   }
 
+  // Searches for messages in Google Chat that the calling user has access to.
+  // Returns a list of messages matching the search criteria.
+  //
+  // To search across all spaces the user has access to, set `parent` to
+  // `spaces/-`. Using any other value for `parent` results in an
+  // `INVALID_ARGUMENT` error. The returned messages have their `name` field
+  // populated with the full resource name, which includes the specific `space`
+  // in which the message resides.
+  //
+  // This API doesn't return all message types. The types of messages listed
+  // below aren't included in the response. Use
+  // [ListMessages][google.chat.v1.ChatService.ListMessages] to list all
+  // messages.
+  //
+  // - Private Messages that are visible to the authenticated user.
+  // - Messages posted by Chat apps in spaces or group chats.
+  // - Messages in a Chat app DM.
+  // - Messages from blocked users.
+  // - Messages in spaces that the caller has muted.
+  //
+  // 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):
+  //
+  //   - `https://www.googleapis.com/auth/chat.messages.readonly`
+  //   - `https://www.googleapis.com/auth/chat.messages`
+  rpc SearchMessages(SearchMessagesRequest) returns (SearchMessagesResponse) {
+    option (google.api.http) = {
+      post: "/v1/{parent=spaces/*}/messages:search"
+      body: "*"
+    };
+    option (google.api.method_signature) = "parent,filter";
+  }
+
   // Gets the metadata of a message attachment. The attachment data is fetched
   // using the [media
   // API](https://developers.google.com/workspace/chat/api/reference/rest/v1/media/download).
@@ -415,19 +450,30 @@ service ChatService {
     option (google.api.method_signature) = "";
   }
 
-  // Returns a list of spaces in a Google Workspace organization based on an
-  // administrator's search. In the request, set `use_admin_access` to `true`.
-  // For an example, see [Search for and manage
+  // Returns a list of spaces in a Google Workspace organization. For an
+  // example, see [Search for and manage
   // spaces](https://developers.google.com/workspace/chat/search-manage-admin).
   //
-  // Requires [user
+  // When `use_admin_access` is set to `false`, the results are limited to
+  // spaces where the calling user is a joined member. To search with
+  // administrator privileges, set `use_admin_access` to `true`.
+  //
+  // Supports the following types of
+  // [authentication](https://developers.google.com/workspace/chat/authenticate-authorize):
+  //
+  // - [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`
+  //
+  // - [User
   // authentication with administrator
   // privileges](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#admin-privileges)
   // and one of the following [authorization
   // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
-  //
-  //   - `https://www.googleapis.com/auth/chat.admin.spaces.readonly`
-  //   - `https://www.googleapis.com/auth/chat.admin.spaces`
+  //     - `https://www.googleapis.com/auth/chat.admin.spaces.readonly`
+  //     - `https://www.googleapis.com/auth/chat.admin.spaces`
   rpc SearchSpaces(SearchSpacesRequest) returns (SearchSpacesResponse) {
     option (google.api.http) = {
       get: "/v1/spaces:search"

package/build/protos/google/chat/v1/message.proto

@@ -28,6 +28,7 @@ import "google/chat/v1/matched_url.proto";
 import "google/chat/v1/reaction.proto";
 import "google/chat/v1/slash_command.proto";
 import "google/chat/v1/space.proto";
+import "google/chat/v1/space_notification_setting.proto";
 import "google/chat/v1/user.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
@@ -112,8 +113,8 @@ message Message {
   //
   // * [Markup
   // syntax](https://developers.google.com/workspace/chat/format-messages)
-  // for bold, italic, strikethrough, monospace, monospace block, and bulleted
-  // list.
+  // for bold, italic, strikethrough, monospace, monospace block, bulleted
+  // list, and block quote.
   //
   // * [User
   // mentions](https://developers.google.com/workspace/chat/format-messages#messages-@mention)
@@ -191,8 +192,8 @@ message Message {
   // Optional. User-uploaded attachment.
   repeated Attachment attachment = 18 [(google.api.field_behavior) = OPTIONAL];
 
-  // Output only. A URL in `spaces.messages.text` that matches a link preview
-  // pattern. For more information, see [Preview
+  // Output only. A URL in the Chat message `text` field that matches a link
+  // preview pattern. For more information, see [Preview
   // links](https://developers.google.com/workspace/chat/preview-links).
   MatchedUrl matched_url = 20 [(google.api.field_behavior) = OUTPUT_ONLY];
 
@@ -677,9 +678,9 @@ message CreateMessageNotificationOptions {
     // (https://developers.google.com/workspace/chat/authenticate-authorize-chat-app).
     NOTIFICATION_TYPE_FORCE_NOTIFY = 2;
 
-    // Silence the notification as if the recipients have [Chat Do Not
-    // Disturb](https://support.google.com/chat/answer/9093489) enabled or
-    // have muted the space.
+    // Do not notify recipients, and do not mark the message as unread.
+    // This behaves similarly to the user muting the conversation or enabling
+    // [Chat Do Not Disturb](https://support.google.com/chat/answer/9093489).
     //
     // Requires [app authentication]
     // (https://developers.google.com/workspace/chat/authenticate-authorize-chat-app).
@@ -830,3 +831,232 @@ message CardWithId {
   // A card. Maximum size is 32 KB.
   google.apps.card.v1.Card card = 2;
 }
+
+// Request message for searching messages.
+message SearchMessagesRequest {
+  // The kinds of view that are supported for partial search results.
+  enum SearchMessagesView {
+    // The default / unset value.
+    // The API will default to the BASIC view.
+    SEARCH_MESSAGES_VIEW_UNSPECIFIED = 0;
+
+    // Includes only the matched messages in the results, but no additional
+    // metadata. This is the default value.
+    SEARCH_MESSAGES_VIEW_BASIC = 1;
+
+    // Includes everything in the results: the matched messages and additional
+    // metadata.
+    SEARCH_MESSAGES_VIEW_FULL = 2;
+  }
+
+  // Required. The resource name of the space to search within.
+  //
+  // To search across all spaces the user has access to, set this field to
+  // `spaces/-`. Using any other value for `parent` results in an
+  // `INVALID_ARGUMENT` error.
+  //
+  // To limit the search to one or more spaces, use `space.name` or
+  // `space.display_name` in the `filter`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
+  ];
+
+  // Required. A search query.
+  //
+  // The query can specify one or more search keywords, which are used to filter
+  // the results,
+  //
+  // You can also filter the results using the following message fields:
+  //
+  // - `create_time`: Accepts a timestamp in
+  //   [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) format and the
+  //   supported comparison operators are: `<` and `>=`.
+  // - `sender.name`: The resource name of the sender (`users/{user}`). Only
+  //   supports `=`. You can use the e-mail as an alias for `{user}`. For
+  //   example, `users/example@gmail.com`, where `example@gmail.com` is the
+  //   e-mail of the Google Chat user.
+  // - `space.name`: The resource name of the space where the message is posted.
+  //   (`spaces/{space}`). Only supports `=`. If this filter is not set, the
+  //   search is performed across all direct messages and spaces the user has
+  //   access to as a space member.
+  // - `space.display_name`: Supports the operator `:` (has) and filters spaces
+  //   based on a partial match of their display name. Results are limited to
+  //   the top five space matches. For example, `space.display_name:Project`
+  //   searches for messages in the top five spaces that contain the word
+  //   "Project" in their display names.
+  // - `attachment`: Supports the operator `:*` (has any) to check for the
+  //   presence of attachments. If `attachment:*` is specified, only messages
+  //   that have at least one attachment are returned.
+  // - `annotations.user_mentions.user.name`: The resource name of the mentioned
+  //   user (`users/{user}`). Only supports `:` (has). For example:
+  //   `annotations.user_mentions.user.name:"users/1234567890"` returns only
+  //   messages that contain a mention to the specified user. Alternatively, the
+  //   alias `me` can be used to filter for messages that mention the caller
+  //   user, for example: `annotations.user_mentions.user.name:users/me`. You
+  //   can also use the e-mail as an alias for `{user}`, for example,
+  //   `users/example@gmail.com`.
+  //
+  // For advanced filtering, the following functions are also available:
+  //
+  // - `has_link()`: Returns only messages that have at least one hyperlink in
+  //   the message text.
+  // - `is_unread()`: Filters out messages that have been read by the calling
+  //   user.
+  //
+  // Using the `space.display_name` filter requires that the calling credentials
+  // include one of the following [authorization
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
+  //
+  // - `https://www.googleapis.com/auth/chat.spaces.readonly`
+  // - `https://www.googleapis.com/auth/chat.spaces`
+  //
+  // Using the `is_unread()` filter requires that the calling credentials
+  // include one of the following [authorization
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
+  //
+  // - `https://www.googleapis.com/auth/chat.users.readstate.readonly`
+  // - `https://www.googleapis.com/auth/chat.users.readstate`
+  //
+  //
+  // Across different fields, only `AND` operators are supported. A valid
+  // example is `sender.name = "users/1234567890" AND is_unread()`. The word
+  // `AND` is optional and is implied if omitted. For example, `sender.name =
+  // "users/1234567890" is_unread()` is valid and is equivalent to the previous
+  // example. An invalid example is `sender.name = "users/1234567890" OR
+  // is_unread()` because `OR` is not supported between different fields.
+  //
+  // Among the same field:
+  //
+  // - `create_time` supports only `AND`, and can only be used to represent
+  //    an interval, such as `create_time >= "2022-01-01T00:00:00+00:00" AND
+  //    create_time < "2023-01-01T00:00:00+00:00"`.
+  // - `sender.name` supports only the `OR` operator, for example:
+  //   `sender.name = "users/1234567890" OR sender.name = "users/0987654321"`.
+  // - `space.name` supports only the `OR` operator, for example:
+  //   `space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI"`.
+  // - `space.display_name` supports the operators `AND` and `OR`, but not a
+  //   mix of both. For example:
+  //   `space.display_name:Project AND space.display_name:Tasks` returns
+  //   messages that are in spaces with display names containing both `Project`
+  //   and `Tasks`, whereas
+  //   `space.display_name:Project OR space.display_name:Tasks` returns messages
+  //   that are in spaces with display names containing either `Project` or
+  //   `Tasks` or both.
+  // - `annotations.user_mentions.user.name` supports the operators `AND` and
+  //   `OR`, but not a mix of both. For example:
+  //   `annotations.user_mentions.user.name:"users/1234567890" AND
+  //   annotations.user_mentions.user.name:"users/0987654321"` returns only
+  //   messages that mentions both users, whereas
+  //   `annotations.user_mentions.user.name:"users/1234567890" OR
+  //   annotations.user_mentions.user.name:"users/0987654321"` returns messages
+  //   that mention either user or both.
+  //
+  // Parentheses are required to disambiguate operator precedence when combining
+  // `AND` and `OR` operators in the same query. For example:
+  // `(sender.name="users/me" OR sender.name="users/123456") AND is_unread()`.
+  // Otherwise, parentheses are optional.
+  //
+  // The following example queries are valid:
+  //
+  // ```
+  // "Pending reports" AND create_time >= "2023-01-01T00:00:00Z"
+  //
+  // sender.name = "users/example@gmail.com"
+  //
+  // annotations.user_mentions.user.name:"users/0987654321"
+  //
+  // attachment:* AND space.name = "spaces/ABCDEFGH"
+  //
+  // tasks AND is_unread() AND sender.name = "users/1234567890"
+  //
+  // "things to do" "urgent"
+  //
+  // (sender.name = "users/1234567890")
+  // AND (create_time < "2023-05-01T00:00:00Z")
+  //
+  // tasks AND space.name = "spaces/ABCDEFGH" AND has_link()
+  //
+  // "project one" is_unread()
+  //
+  // space.display_name:Project tasks
+  // ```
+  //
+  // The maximum query length is 1,000 characters.
+  //
+  // Invalid queries are rejected by the server with an `INVALID_ARGUMENT`
+  // error.
+  string filter = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The maximum number of results to return. The service may return
+  // fewer than this value.
+  //
+  // If unspecified, at most 25 are returned.
+  //
+  // The maximum value is 100. If you use a value more than 100, it's
+  // automatically changed to 100.
+  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A token, received from the previous search messages 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 = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. How the results list is ordered.
+  //
+  // Supported attributes to order by are:
+  //
+  // - `create_time`: Sorts the results by the time of the message creation.
+  //   Default value.
+  // - `relevance`: Sorts the results by relevance.
+  //   [Developer Preview](https://developers.google.com/workspace/preview).
+  //
+  // The default ordering is `create_time desc`. Only a single order per query
+  // (`create_time` or `relevance`) is supported. Only descending order (`desc`)
+  // is supported, and it must be specified after the order attribute.
+  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Specifies what kind of search results view to return. The default
+  // is `SEARCH_MESSAGES_VIEW_BASIC`.
+  SearchMessagesView view = 7 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for searching messages.
+message SearchMessagesResponse {
+  // The list of search results that matched the query.
+  repeated SearchMessageResult results = 1;
+
+  // A token that can be used to retrieve the next page. If this field is empty,
+  // there are no subsequent pages.
+  string next_page_token = 2;
+}
+
+// A single result item from a message search.
+message SearchMessageResult {
+  // The matched message.
+  Message message = 1;
+
+  // Indicates if the matched message is read by the calling user.
+  //
+  // Only returned if the request view is `SEARCH_MESSAGES_VIEW_FULL` and the
+  // calling credentials include one of the following [authorization
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
+  //
+  //   - `https://www.googleapis.com/auth/chat.users.readstate.readonly`
+  //   - `https://www.googleapis.com/auth/chat.users.readstate`
+  optional bool read = 3;
+
+  // The mute setting of the calling user for the space where the message is
+  // posted. The caller app can use this information to decide how to process
+  // the message depending on whether the space is muted for the user or not.
+  //
+  // Only returned if the request view is `SEARCH_MESSAGES_VIEW_FULL` and the
+  // calling credentials include the following [authorization
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
+  //
+  //   - `https://www.googleapis.com/auth/chat.users.spacesettings`
+  SpaceNotificationSetting.MuteSetting space_mute_setting = 4;
+}

package/build/protos/google/chat/v1/space.proto

@@ -76,17 +76,20 @@ message Space {
     // 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.
+    // 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.
+    // Spaces that don't support message threading. This space threading state
+    // is only used for special cases including:
+    //
+    // * Continuous meeting chat where threading is intentionally turned off.
+    // * Legacy group conversations that were created prior to 2022.
     UNTHREADED_MESSAGES = 4;
   }
 
@@ -765,9 +768,6 @@ message SearchSpacesRequest {
   // Requires either the `chat.admin.spaces.readonly` or `chat.admin.spaces`
   // [OAuth 2.0
   // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
-  //
-  // This method currently only supports admin access, thus only `true` is
-  // accepted for this field.
   bool use_admin_access = 1;
 
   // The maximum number of spaces to return. The service may return fewer than
@@ -789,7 +789,8 @@ message SearchSpacesRequest {
 
   // Required. A search query.
   //
-  // You can search by using the following parameters:
+  // You can search by using the following parameters when `useAdminAccess`
+  // is set to `true`:
   //
   // - `create_time`
   // - `customer`
@@ -799,18 +800,27 @@ message SearchSpacesRequest {
   // - `space_history_state`
   // - `space_type`
   //
+  // When `useAdminAccess` is set to `false`:
+  //
+  // - `display_name`
+  // - `external_user_allowed`
+  // - `space_type`
+  //
   // `create_time` and `last_active_time` accept a timestamp in
   // [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) format and the supported
   // comparison operators are: `=`, `<`, `>`, `<=`, `>=`.
   //
-  // `customer` is required and is used to indicate which customer
-  // to fetch spaces from. `customers/my_customer` is the only supported value.
+  // `customer` is required when `useAdminAccess` is set to `true`, and is
+  // used to indicate which customer to fetch spaces from.
+  // `customers/my_customer` is the only supported value.
   //
   // `display_name` only accepts the `HAS` (`:`) operator. The text to
   // match is first tokenized into tokens and each token is prefix-matched
   // case-insensitively and independently as a substring anywhere in the space's
   // `display_name`. For example, `Fun Eve` matches `Fun event` or `The
-  // evening was fun`, but not `notFun event` or `even`.
+  // evening was fun`, but not `notFun event` or `even`. When `useAdminAccess`
+  // is set to `false`, `display_name` is required to retrieve meaningful
+  // results. Otherwise, the default behavior is to return an empty response.
   //
   // `external_user_allowed` accepts either `true` or `false`.
   //
@@ -833,7 +843,8 @@ message SearchSpacesRequest {
   // < "2022-01-01T00:00:00+00:00" AND last_active_time >
   // "2023-01-01T00:00:00+00:00"`.
   //
-  // The following example queries are valid:
+  // The following example queries are valid when `useAdminAccess` is set to
+  // `true`:
   //
   // ```
   // customer = "customers/my_customer" AND space_type = "SPACE"
@@ -855,6 +866,21 @@ message SearchSpacesRequest {
   // "2020-01-01T00:00:00+00:00") AND (external_user_allowed = "true") AND
   // (space_history_state = "HISTORY_ON" OR space_history_state = "HISTORY_OFF")
   // ```
+  //
+  // The following example queries are valid when `useAdminAccess` is set to
+  // `false`:
+  //
+  // ```
+  // display_name:"Hello World" AND space_type = "SPACE"
+  //
+  // (display_name:"Hello" OR display_name:"Fun") AND space_type = "SPACE"
+  //
+  // (external_user_allowed = "true" AND space_type = "SPACE") // Returns an
+  // empty response.
+  //
+  // (external_user_allowed = "true" AND display_name:"Hello" AND space_type =
+  // "SPACE")
+  // ```
   string query = 4 [(google.api.field_behavior) = REQUIRED];
 
   // Optional. How the list of spaces is ordered.
@@ -867,13 +893,17 @@ message SearchSpacesRequest {
   // any topic of this space.
   // - `create_time` — Denotes the time of the space creation.
   //
+  // When `useAdminAccess` is `false`, only `create_time` and `relevance` are
+  // supported for ordering. Only `DESC` is supported for these fields in
+  // non-admin searches.
+  //
   // Valid ordering operation values are:
   //
   // - `ASC` for ascending. Default value.
   //
   // - `DESC` for descending.
   //
-  // The supported syntax are:
+  // The supported syntax are when `useAdminAccess` is set to `true`:
   //
   // - `membership_count.joined_direct_human_user_count DESC`
   // - `membership_count.joined_direct_human_user_count ASC`
@@ -881,13 +911,27 @@ message SearchSpacesRequest {
   // - `last_active_time ASC`
   // - `create_time DESC`
   // - `create_time ASC`
+  //
+  // When `useAdminAccess` is set to `false`:
+  //
+  // - `create_time DESC`
+  // - `relevance DESC`
   string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response with a list of spaces corresponding to the search spaces request.
 message SearchSpacesResponse {
-  // A page of the requested spaces.
-  repeated Space spaces = 1;
+  // A single result item from a space search.
+  message SearchSpaceResult {
+    // Output only. The matched space.
+    Space space = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+  }
+
+  // Deprecated: Please use the new `results` field instead.
+  // A page of the requested spaces. This field will be populated only when
+  // `useAdminAccess` is set to `true` and deprecated in favor of the new
+  // `results` field.
+  repeated Space spaces = 1 [deprecated = true];
 
   // A token that can be used to retrieve the next page. If this field is empty,
   // there are no subsequent pages.
@@ -896,6 +940,10 @@ message SearchSpacesResponse {
   // The total number of spaces that match the query, across all pages. If the
   // result is over 10,000 spaces, this value is an estimate.
   int32 total_size = 3;
+
+  // Output only. The list of search results that matched the query.
+  repeated SearchSpaceResult results = 4
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Request for deleting a space.