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 call this method, you must use user authentication. To list events from a space, the authenticated user must be a member of the space.

Prerequisites

Python

Python 3.6 or greater
The pip package management tool
The latest Google client libraries for Python. To install or update them, run the following command in your command-line interface:
```
pip3 install --upgrade google-api-python-client google-auth-oauthlib
```
A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
Authorization configured for the Chat app. Listing SpaceEvent resources supports the following authentication methods:
- User authentication: requires a scope that supports the event types requested. To identify a scope, see Scopes by event type.

List space events

To list space events from a Chat space, do the following:

Call the list method on the SpaceEvent resource.
Specify which event types to list using the filter field. You must specify at least one event type, and you can also filter by date. For a list of supported event types, see eventType field.
With user authentication, 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.

In the following code sample, you list events about new memberships and messages in a space.

Python

In your working directory, create a file named chat_space_event_list.py.

Include the following code in chat_space_event_list.py:

"""Lists SpaceEvent resources from the Chat API."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.memberships.readonly",
"https://www.googleapis.com/auth/chat.messages.readonly"]

# Authenticate with Google Workspace
# and get user authorization.
flow = InstalledAppFlow.from_client_secrets_file(
            'client_secrets.json', SCOPES)
creds = flow.run_local_server()

# Build a service endpoint for Chat API.
chat = build(
  'chat',
  'v1',
  credentials=creds,
)

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

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

    # A required filter. Filters and returns events about new memberships and messages
    filter='event_types:"google.workspace.chat.membership.v1.created" OR event_types:"google.workspace.chat.message.v1.created"'

).execute()

# Prints details about the created space events.
print(result)

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
In your working directory, build and run the sample:
```
python3 chat_space_event_list.py
```

The Chat API returns a list of SpaceEvent resources events about new memberships and messages.

Customize pagination

Optionally, pass the following query parameters to customize pagination:

pageSize: The maximum number of SpaceEvent resources to return. The service might return fewer than this value. Negative values return an INVALID_ARGUMENT error.
pageToken: A page token, received from a previous list space events call. Provide this token to retrieve the subsequent page. When paginating, the filter value should match the call that provided the page token. Passing a different value might lead to unexpected results.

List events from a Google Chat space

Prerequisites

Python

List space events

Python

Customize pagination

Related topics