List events from a Google Chat space

This guide explains how to use the list() method on the SpaceEvent resource of the Google Chat API to list changes to resources in a space.

The SpaceEvent resource represents a change to the target space, including child resources of the space such as messages, reactions, and memberships. For more information about the list of event types and event payloads supported, see the eventType and payload fields of the SpaceEvent resource reference documentation.

You can list events up to 28 days before the time of the request. The server returns events that contain the most recent version of the affected resource. For example, if you list events about new space members, the server returns Membership resources that contain the latest membership details. If new members were removed during the requested period, the event payload contains an empty Membership resource.

To list events from a space, the authenticated user or Chat app must be a member of the space.

Prerequisites

Node.js

Python

List space events (user authentication)

To list space events from a Chat space, pass the following in your request:

  • Specify one or more authorization scopes to support each event type in your request. As a best practice, choose the most restrictive scope that still allows your app to function. To choose a scope, see the Authentication and authorization overview.

  • Call the ListSpaceEvents() method, passing the filter of event types to list. You must specify at least one event type, and you can also filter by date. For a list of supported event types, see the eventType field of the SpaceEvent resource reference documentation.

The following example lists events about new memberships and messages in a space:

Node.js

chat/client-libraries/cloud/list-space-events-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

// Authorization scopes based on the event types
const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.memberships.readonly',
  'https://www.googleapis.com/auth/chat.messages.readonly',
];

// This sample shows how to list space events with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here
    parent: 'spaces/SPACE_NAME',
    // A required filter. Filters events about new memberships and messages.
    filter:
      'eventTypes:"google.workspace.chat.membership.v1.created" OR eventTypes:"google.workspace.chat.message.v1.created"',
  };

  // Make the request
  const pageResult = chatClient.listSpaceEventsAsync(request);

  // Handle the response. Iterating over pageResult will yield results and
  // resolve additional pages automatically.
  for await (const response of pageResult) {
    console.log(response);
  }
}

await main();

To run this sample, replace SPACE_NAME with the ID from the space's name. You can obtain the ID by calling the ListSpaces() method or from the space's URL.

The Chat API returns a list of paginated list of space events about new memberships and messages.

List space events (Chat app authentication)

App authentication requires one-time administrator approval.

To list space events from a space with app authentication and the Chat REST API, pass the following in your request:

  • Specify one or more authorization scopes to support each event type in your request. As a best practice, choose the most restrictive scope that still allows your app to function. To learn more about choosing a scope, see the Authentication and authorization overview.
    • 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
  • Call the list method on the spaceEvents resource.
  • Pass the name of the space to list messages from.
  • Pass a filter to query specific event types.

Create an API key

To call a Developer Preview API method, you must use a non-public developer preview version of the API discovery document. To authenticate the request, you must pass an API key.

To create the API Key, open your app's Google Cloud project and do the following:

  1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

    Go to Credentials

  2. Click Create credentials > API key.
  3. Your new API key is displayed.
    • Click Copy to copy your API key for use in your app's code. The API key can also be found in the "API Keys" section of your project's credentials.
    • To prevent unauthorized use, we recommend restricting where and for which APIs the API key can be used. For more details, see Add API restrictions.

Write a script that calls Chat API

Here's how to list space events with app authentication and the Chat REST API:

Python

  1. In your working directory, create a file named chat_spaceevents_list_app.py.

  2. Include the following code in chat_spaceevents_list_app.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Define your app's authorization scopes.
# Set authorization scopes based on the
# event type. For example, if you are getting a space event
# about a new membership, use the `chat.app.memberships.readonly` scope.
#
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["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"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then lists space events from a specified space.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().spaceEvents().list(

        # The space to list events from.
        #
        # Replace SPACE_NAME with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE_NAME',

        # A required filter. Filters events by event type.
        #
        # Update this filter to match your requirements.
        filter='eventTypes:"google.workspace.chat.message.v1.created"'

    ).execute()

    # Print Chat API's response in your command line interface.
    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace the following:

    • API_KEY: the API key you created to build the service endpoint for Chat API.
    • SPACE_NAME: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.

  4. In your working directory, build and run the sample:

    python3 chat_spaceevents_list_app.py

The Chat API returns a list of paginated list of space events about new memberships and messages.