Search messages

This document explains how to use the search method on the Message resource of the Google Chat API to search for messages that the authenticated user has access to.

With user authentication, you can search for messages across all conversations the user has joined, or within a specific conversation. For example, you can search for messages that contain specific keywords, mention the user, are unread, or have attachments.

In the Chat API, a Chat message is represented by the Message resource. While Chat users can only send messages that contain text, Chat apps can use many other messaging features, including displaying static or interactive user interfaces, collecting information from users, and delivering messages privately. To learn more about messaging features available for the Chat API, see the Google Chat messages overview.

Prerequisites

Node.js

Python

Java

Apps Script

Search for messages

To search for messages with user authentication, pass the following in your request:

  • Specify the chat.messages.readonly or chat.messages authorization scope.

  • Call the SearchMessages method.

  • Set parent to spaces/- to search within all spaces the user is a member of. Using any other value results in an error.

  • In the filter field, specify a search query string. The query can include keywords and filters.

The following code sample searches for unread messages that contain the keyword "tasks":

Node.js

/**
 * Searches for messages in Google Chat.
 * @param {string} filter The search query.
 */
asyncfunctionsearchMessages(filter){
const{ChatServiceClient}=require('@google-apps/chat').v1;
// Instantiates a client
constchatClient=newChatServiceClient();
// See https://github.com/googleworkspace/node-samples/blob/main/chat/client-libraries/cloud/authentication-utils.js
// for an example of how to authenticate the request.
// Construct request
constrequest={
// Parent must be "spaces/-" to search across all spaces.
parent:'spaces/-',
filter:filter,
};
// Run request
constiterable=awaitchatClient.searchMessagesAsync(request);
forawait(constresponseofiterable){
console.log(response);
}
}
searchMessages('tasks AND is_unread()');

Python

fromgoogle.appsimport chat_v1
defsearch_messages(filter_str: str):
"""
 Searches for messages in Google Chat.
 Args:
 filter_str: The search query.
 """
 # Create a client
 client = chat_v1.ChatServiceClient()
 # See https://github.com/googleworkspace/python-samples/blob/main/chat/client-libraries/cloud/authentication_utils.py
 # for an example of how to authenticate the request.
 # Initialize request argument
 request = chat_v1.SearchMessagesRequest(
 # Parent must be "spaces/-" to search across all spaces.
 parent="spaces/-",
 filter=filter_str
 )
 # Make the request
 page_result = client.search_messages(request=request)
 # Handle the response
 for response in page_result:
 print(response)
search_messages('tasks AND is_unread()')

Java

importcom.google.chat.v1.ChatServiceClient;
importcom.google.chat.v1.SearchMessageResult;
importcom.google.chat.v1.SearchMessagesRequest;
publicclass SearchMessages{
publicstaticvoidmain(String[]args)throwsException{
searchMessages("tasks AND is_unread()");
}
/**
 * Searches for messages in Google Chat.
 *
 * @param filter The search query.
 */
publicstaticvoidsearchMessages(Stringfilter)throwsException{
// See https://github.com/googleworkspace/java-samples/blob/main/chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/AuthenticationUtils.java
// for an example of how to authenticate the request.
try(ChatServiceClientchatServiceClient=ChatServiceClient.create()){
SearchMessagesRequestrequest=
SearchMessagesRequest.newBuilder()
.setParent("spaces/-")
.setFilter(filter)
.build();
for(SearchMessageResultresult:chatServiceClient.searchMessages(request).iterateAll()){
System.out.println(result.getMessage().getText());
}
}
}
}

Apps Script

javascript /** * Searches for messages in Google Chat. */ function searchMessages() { const filter = 'tasks AND is_unread()'; const url = 'https://chat.googleapis.com/v1/spaces/-/messages:search'; const request_payload = { filter: filter }; try { const response = UrlFetchApp.fetch(url, { method: 'post', headers: { 'Authorization': 'Bearer ' + ScriptApp.getOAuthToken() }, contentType: 'application/json', payload: JSON.stringify(request_payload) }); if (response.results) { for (const result of response.results) { console.log('Message text: %s', result.message.text); } } else { console.log('No messages found.'); } } catch (err) { console.log('Failed to search messages with error: %s', err.message); } }

Use search filters and operators

You can refine your search results by using keywords, fields, and functions in the filter field. For more information, see SearchMessagesRequest.

To search for messages that contain specific text, enter the keywords. For example, to search for pending reports, use pending reports.

Search by field

You can filter results by specific message or space fields. For example:

  • create_time: Filter by the time the message was created. Example: create_time > "2023年01月01日T00:00:00Z"
  • sender.name: Filter by the resource name of the sender. Example: sender.name = "users/1234567890"
  • space.name: Limit the search to a specific space. Example: space.name = "spaces/ABCDEFGH"
  • space.display_name: Filter spaces based on a partial match of their display name. Results are limited to the top five space matches. Example: space.display_name:Project
  • attachment: Check for the presence of attachments. Example: attachment:*
  • annotations.user_mentions.user.name: Filter by mentions. Example: annotations.user_mentions.user.name:"users/me"

Search using functions

Advanced filtering is available through the following functions:

  • has_link: Returns messages that contain at least one hyperlink.
  • is_unread: Returns messages that haven't been read by the user.

Across different fields, only AND operators are supported. For example: sender.name = "users/me" AND is_unread().

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026年07月30日 UTC.