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.
 */
async function searchMessages(filter) {
  const {ChatServiceClient} = require('@google-apps/chat').v1;

  // Instantiates a client
  const chatClient = new ChatServiceClient();

  // 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
  const request = {
    // Parent must be "spaces/-" to search across all spaces.
    parent: 'spaces/-',
    filter: filter,
  };

  // Run request
  const iterable = await chatClient.searchMessagesAsync(request);
  for await (const response of iterable) {
    console.log(response);
  }
}

searchMessages('tasks AND is_unread()');

Python

from google.apps import chat_v1

def search_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

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.SearchMessageResult;
import com.google.chat.v1.SearchMessagesRequest;

public class SearchMessages {
  public static void main(String[] args) throws Exception {
    searchMessages("tasks AND is_unread()");
  }

  /**
   * Searches for messages in Google Chat.
   *
   * @param filter The search query.
   */
  public static void searchMessages(String filter) throws Exception {
    // 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 (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      SearchMessagesRequest request =
          SearchMessagesRequest.newBuilder()
              .setParent("spaces/-")
              .setFilter(filter)
              .build();
      for (SearchMessageResult result : 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-01T00: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().