Skip to content

Commit 2aa36cf

Browse files
gcf-owl-bot[bot]gcf-owl-bot[bot]
authored
feat: [AppsChat] Addition of the Search Messages API (#9417)
* feat: Addition of the Search Messages API docs: Update reference documentation for the Search Messages API, and the message and Space resources PiperOrigin-RevId: 956488851 Source-Link: googleapis/googleapis@36d9a9b Source-Link: googleapis/googleapis-gen@67e994c Copy-Tag: eyJwIjoiQXBwc0NoYXQvLk93bEJvdC55YW1sIiwiaCI6IjY3ZTk5NGMxNGU4ZGUxNTk5Y2M0OThiYmQ1ZDM5MzBlNThiNWQ5MzkifQ== * 🦉 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>
1 parent 5923eb6 commit 2aa36cf

16 files changed

Lines changed: 1661 additions & 26 deletions

‎AppsChat/metadata/Chat/V1/ChatService.php‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎AppsChat/metadata/Chat/V1/Message.php‎

Lines changed: 2 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎AppsChat/samples/V1/ChatServiceClient/search_messages.php‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
<?php
2+
/*
3+
* Copyright 2026 Google LLC
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* https://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
/*
19+
* GENERATED CODE WARNING
20+
* This file was automatically generated - do not edit!
21+
*/
22+
23+
require_once __DIR__ . '/../../../vendor/autoload.php';
24+
25+
// [START chat_v1_generated_ChatService_SearchMessages_sync]
26+
use Google\ApiCore\ApiException;
27+
use Google\ApiCore\PagedListResponse;
28+
use Google\Apps\Chat\V1\Client\ChatServiceClient;
29+
use Google\Apps\Chat\V1\SearchMessageResult;
30+
use Google\Apps\Chat\V1\SearchMessagesRequest;
31+
32+
/**
33+
* Searches for messages in Google Chat that the calling user has access to.
34+
* Returns a list of messages matching the search criteria.
35+
*
36+
* To search across all spaces the user has access to, set `parent` to
37+
* `spaces/-`. Using any other value for `parent` results in an
38+
* `INVALID_ARGUMENT` error. The returned messages have their `name` field
39+
* populated with the full resource name, which includes the specific `space`
40+
* in which the message resides.
41+
*
42+
* This API doesn't return all message types. The types of messages listed
43+
* below aren't included in the response. Use
44+
* [ListMessages][google.chat.v1.ChatService.ListMessages] to list all
45+
* messages.
46+
*
47+
* - Private Messages that are visible to the authenticated user.
48+
* - Messages posted by Chat apps in spaces or group chats.
49+
* - Messages in a Chat app DM.
50+
* - Messages from blocked users.
51+
* - Messages in spaces that the caller has muted.
52+
*
53+
* Requires [user
54+
* authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
55+
* with one of the following [authorization
56+
* scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
57+
*
58+
* - `https://www.googleapis.com/auth/chat.messages.readonly`
59+
* - `https://www.googleapis.com/auth/chat.messages`
60+
*
61+
* @param string $formattedParent The resource name of the space to search within.
62+
*
63+
* To search across all spaces the user has access to, set this field to
64+
* `spaces/-`. Using any other value for `parent` results in an
65+
* `INVALID_ARGUMENT` error.
66+
*
67+
* To limit the search to one or more spaces, use `space.name` or
68+
* `space.display_name` in the `filter`. Please see
69+
* {@see ChatServiceClient::spaceName()} for help formatting this field.
70+
* @param string $filter A search query.
71+
*
72+
* The query can specify one or more search keywords, which are used to filter
73+
* the results,
74+
*
75+
* You can also filter the results using the following message fields:
76+
*
77+
* - `create_time`: Accepts a timestamp in
78+
* [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) format and the
79+
* supported comparison operators are: `<` and `>=`.
80+
* - `sender.name`: The resource name of the sender (`users/{user}`). Only
81+
* supports `=`. You can use the e-mail as an alias for `{user}`. For
82+
* example, `users/example&#64;gmail.com`, where `example&#64;gmail.com` is the
83+
* e-mail of the Google Chat user.
84+
* - `space.name`: The resource name of the space where the message is posted.
85+
* (`spaces/{space}`). Only supports `=`. If this filter is not set, the
86+
* search is performed across all direct messages and spaces the user has
87+
* access to as a space member.
88+
* - `space.display_name`: Supports the operator `:` (has) and filters spaces
89+
* based on a partial match of their display name. Results are limited to
90+
* the top five space matches. For example, `space.display_name:Project`
91+
* searches for messages in the top five spaces that contain the word
92+
* "Project" in their display names.
93+
* - `attachment`: Supports the operator `:*` (has any) to check for the
94+
* presence of attachments. If `attachment:*` is specified, only messages
95+
* that have at least one attachment are returned.
96+
* - `annotations.user_mentions.user.name`: The resource name of the mentioned
97+
* user (`users/{user}`). Only supports `:` (has). For example:
98+
* `annotations.user_mentions.user.name:"users/1234567890"` returns only
99+
* messages that contain a mention to the specified user. Alternatively, the
100+
* alias `me` can be used to filter for messages that mention the caller
101+
* user, for example: `annotations.user_mentions.user.name:users/me`. You
102+
* can also use the e-mail as an alias for `{user}`, for example,
103+
* `users/example&#64;gmail.com`.
104+
*
105+
* For advanced filtering, the following functions are also available:
106+
*
107+
* - `has_link()`: Returns only messages that have at least one hyperlink in
108+
* the message text.
109+
* - `is_unread()`: Filters out messages that have been read by the calling
110+
* user.
111+
*
112+
* Using the `space.display_name` filter requires that the calling credentials
113+
* include one of the following [authorization
114+
* scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
115+
*
116+
* - `https://www.googleapis.com/auth/chat.spaces.readonly`
117+
* - `https://www.googleapis.com/auth/chat.spaces`
118+
*
119+
* Using the `is_unread()` filter requires that the calling credentials
120+
* include one of the following [authorization
121+
* scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
122+
*
123+
* - `https://www.googleapis.com/auth/chat.users.readstate.readonly`
124+
* - `https://www.googleapis.com/auth/chat.users.readstate`
125+
*
126+
*
127+
* Across different fields, only `AND` operators are supported. A valid
128+
* example is `sender.name = "users/1234567890" AND is_unread()`. The word
129+
* `AND` is optional and is implied if omitted. For example, `sender.name =
130+
* "users/1234567890" is_unread()` is valid and is equivalent to the previous
131+
* example. An invalid example is `sender.name = "users/1234567890" OR
132+
* is_unread()` because `OR` is not supported between different fields.
133+
*
134+
* Among the same field:
135+
*
136+
* - `create_time` supports only `AND`, and can only be used to represent
137+
* an interval, such as `create_time >= "2022-01-01T00:00:00+00:00" AND
138+
* create_time < "2023-01-01T00:00:00+00:00"`.
139+
* - `sender.name` supports only the `OR` operator, for example:
140+
* `sender.name = "users/1234567890" OR sender.name = "users/0987654321"`.
141+
* - `space.name` supports only the `OR` operator, for example:
142+
* `space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI"`.
143+
* - `space.display_name` supports the operators `AND` and `OR`, but not a
144+
* mix of both. For example:
145+
* `space.display_name:Project AND space.display_name:Tasks` returns
146+
* messages that are in spaces with display names containing both `Project`
147+
* and `Tasks`, whereas
148+
* `space.display_name:Project OR space.display_name:Tasks` returns messages
149+
* that are in spaces with display names containing either `Project` or
150+
* `Tasks` or both.
151+
* - `annotations.user_mentions.user.name` supports the operators `AND` and
152+
* `OR`, but not a mix of both. For example:
153+
* `annotations.user_mentions.user.name:"users/1234567890" AND
154+
* annotations.user_mentions.user.name:"users/0987654321"` returns only
155+
* messages that mentions both users, whereas
156+
* `annotations.user_mentions.user.name:"users/1234567890" OR
157+
* annotations.user_mentions.user.name:"users/0987654321"` returns messages
158+
* that mention either user or both.
159+
*
160+
* Parentheses are required to disambiguate operator precedence when combining
161+
* `AND` and `OR` operators in the same query. For example:
162+
* `(sender.name="users/me" OR sender.name="users/123456") AND is_unread()`.
163+
* Otherwise, parentheses are optional.
164+
*
165+
* The following example queries are valid:
166+
*
167+
* ```
168+
* "Pending reports" AND create_time >= "2023-01-01T00:00:00Z"
169+
*
170+
* sender.name = "users/example&#64;gmail.com"
171+
*
172+
* annotations.user_mentions.user.name:"users/0987654321"
173+
*
174+
* attachment:* AND space.name = "spaces/ABCDEFGH"
175+
*
176+
* tasks AND is_unread() AND sender.name = "users/1234567890"
177+
*
178+
* "things to do" "urgent"
179+
*
180+
* (sender.name = "users/1234567890")
181+
* AND (create_time < "2023-05-01T00:00:00Z")
182+
*
183+
* tasks AND space.name = "spaces/ABCDEFGH" AND has_link()
184+
*
185+
* "project one" is_unread()
186+
*
187+
* space.display_name:Project tasks
188+
* ```
189+
*
190+
* The maximum query length is 1,000 characters.
191+
*
192+
* Invalid queries are rejected by the server with an `INVALID_ARGUMENT`
193+
* error.
194+
*/
195+
function search_messages_sample(string $formattedParent, string $filter): void
196+
{
197+
// Create a client.
198+
$chatServiceClient = new ChatServiceClient();
199+
200+
// Prepare the request message.
201+
$request = (new SearchMessagesRequest())
202+
->setParent($formattedParent)
203+
->setFilter($filter);
204+
205+
// Call the API and handle any network failures.
206+
try {
207+
/** @var PagedListResponse $response */
208+
$response = $chatServiceClient->searchMessages($request);
209+
210+
/** @var SearchMessageResult $element */
211+
foreach ($response as $element) {
212+
printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
213+
}
214+
} catch (ApiException $ex) {
215+
printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
216+
}
217+
}
218+
219+
/**
220+
* Helper to execute the sample.
221+
*
222+
* This sample has been automatically generated and should be regarded as a code
223+
* template only. It will require modifications to work:
224+
* - It may require correct/in-range values for request initialization.
225+
* - It may require specifying regional endpoints when creating the service client,
226+
* please see the apiEndpoint client configuration option for more details.
227+
*/
228+
function callSample(): void
229+
{
230+
$formattedParent = ChatServiceClient::spaceName('[SPACE]');
231+
$filter = '[FILTER]';
232+
233+
search_messages_sample($formattedParent, $filter);
234+
}
235+
// [END chat_v1_generated_ChatService_SearchMessages_sync]

‎AppsChat/src/Chat/V1/Client/ChatServiceClient.php‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@
8080
use Google\Apps\Chat\V1\PositionSectionRequest;
8181
use Google\Apps\Chat\V1\PositionSectionResponse;
8282
use Google\Apps\Chat\V1\Reaction;
83+
use Google\Apps\Chat\V1\SearchMessagesRequest;
8384
use Google\Apps\Chat\V1\SearchSpacesRequest;
8485
use Google\Apps\Chat\V1\Section;
8586
use Google\Apps\Chat\V1\SetUpSpaceRequest;
@@ -151,6 +152,7 @@
151152
* @method PromiseInterface<Availability> markAsDoNotDisturbAsync(MarkAsDoNotDisturbRequest $request, array $optionalArgs = [])
152153
* @method PromiseInterface<MoveSectionItemResponse> moveSectionItemAsync(MoveSectionItemRequest $request, array $optionalArgs = [])
153154
* @method PromiseInterface<PositionSectionResponse> positionSectionAsync(PositionSectionRequest $request, array $optionalArgs = [])
155+
* @method PromiseInterface<PagedListResponse> searchMessagesAsync(SearchMessagesRequest $request, array $optionalArgs = [])
154156
* @method PromiseInterface<PagedListResponse> searchSpacesAsync(SearchSpacesRequest $request, array $optionalArgs = [])
155157
* @method PromiseInterface<Space> setUpSpaceAsync(SetUpSpaceRequest $request, array $optionalArgs = [])
156158
* @method PromiseInterface<Availability> updateAvailabilityAsync(UpdateAvailabilityRequest $request, array $optionalArgs = [])
@@ -2397,6 +2399,58 @@ public function positionSection(PositionSectionRequest $request, array $callOpti
23972399
return $this->startApiCall('PositionSection', $request, $callOptions)->wait();
23982400
}
23992401

2402+
/**
2403+
* Searches for messages in Google Chat that the calling user has access to.
2404+
* Returns a list of messages matching the search criteria.
2405+
*
2406+
* To search across all spaces the user has access to, set `parent` to
2407+
* `spaces/-`. Using any other value for `parent` results in an
2408+
* `INVALID_ARGUMENT` error. The returned messages have their `name` field
2409+
* populated with the full resource name, which includes the specific `space`
2410+
* in which the message resides.
2411+
*
2412+
* This API doesn't return all message types. The types of messages listed
2413+
* below aren't included in the response. Use
2414+
* [ListMessages][google.chat.v1.ChatService.ListMessages] to list all
2415+
* messages.
2416+
*
2417+
* - Private Messages that are visible to the authenticated user.
2418+
* - Messages posted by Chat apps in spaces or group chats.
2419+
* - Messages in a Chat app DM.
2420+
* - Messages from blocked users.
2421+
* - Messages in spaces that the caller has muted.
2422+
*
2423+
* Requires [user
2424+
* authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
2425+
* with one of the following [authorization
2426+
* scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):
2427+
*
2428+
* - `https://www.googleapis.com/auth/chat.messages.readonly`
2429+
* - `https://www.googleapis.com/auth/chat.messages`
2430+
*
2431+
* The async variant is {@see ChatServiceClient::searchMessagesAsync()} .
2432+
*
2433+
* @example samples/V1/ChatServiceClient/search_messages.php
2434+
*
2435+
* @param SearchMessagesRequest $request A request to house fields associated with the call.
2436+
* @param array $callOptions {
2437+
* Optional.
2438+
*
2439+
* @type RetrySettings|array $retrySettings
2440+
* Retry settings to use for this call. Can be a {@see RetrySettings} object, or an
2441+
* associative array of retry settings parameters. See the documentation on
2442+
* {@see RetrySettings} for example usage.
2443+
* }
2444+
*
2445+
* @return PagedListResponse
2446+
*
2447+
* @throws ApiException Thrown if the API call fails.
2448+
*/
2449+
public function searchMessages(SearchMessagesRequest $request, array $callOptions = []): PagedListResponse
2450+
{
2451+
return $this->startApiCall('SearchMessages', $request, $callOptions);
2452+
}
2453+
24002454
/**
24012455
* Returns a list of spaces in a Google Workspace organization based on an
24022456
* administrator's search. In the request, set `use_admin_access` to `true`.

‎AppsChat/src/Chat/V1/CreateMessageNotificationOptions/NotificationType.php‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)