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
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
client_secrets.json
to your local directory.
- Choose an authorization scope that supports user authentication.
List space events
To list space events from a Chat space, do the following:
- Call the
list
method on theSpaceEvent
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, seeeventType
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 thespaces.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 ofSpaceEvent
resources to return. The service might return fewer than this value. Negative values return anINVALID_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.