List users and Google Chat apps in a space

This guide explains how to use the list method on the membership resource of the Google Chat API to list users and Chat app in a space as a paginated, filterable list of memberships in a space. Listing memberships with app authentication lists memberships in spaces that the Chat app has access to, but excludes Chat app memberships, including its own. Listing memberships with User authentication lists memberships in spaces that the authenticated user has access to.

The Membership resource represents whether a human user or Google Chat app is invited to, part of, or absent from a 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 google-auth
  • 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 memberships supports both of the following authentication methods:

List users and Chat app in a space with user authentication

To list users and Chat app in a space that the authenticated user has access to, pass the following in your request:

The following example lists human space members (not space managers) visible to the authenticated user because filter is set to ROLE_Member:

Python

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

  2. Include the following code in chat_member_list_user.py:

    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"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then lists human space members (but not space managers) in a
    specified space.
    '''

    # 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().members().list(

        # The space for which to list memberships.
        parent = 'spaces/SPACE',

        # An optional filter that returns only human space members.
        filter = 'member.type = "HUMAN" AND role = "ROLE_MEMBER"'

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace SPACE with 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_member_list_user.py

The Google Chat API returns a list of human space members (excluding space managers) and app members from the specified space.

List users and Chat app in a space with app authentication

To list users and Chat app in a space that the authenticated app has access to, pass the following in your request:

The following example lists human space members (not space managers) visible to the Chat app:

Python

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

  2. Include the following code in chat_member_list_app.py:

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

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

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

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=CREDENTIALS)

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

        # The space for which to list memberships.
        parent = 'spaces/SPACE',

        # An optional filter that returns only human space members.
        filter = 'member.type = "HUMAN" AND role = "ROLE_MEMBER"'

    ).execute()

print(result)

  3. In the code, replace SPACE with 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_member_list_app.py

The Google Chat API returns a list of human space members (excluding space managers) from the specified space.

Customize pagination or filter the list

To list the memberships, pass the following query parameters to customize pagination of, or filter, listed memberships:

  • pageSize: The maximum number of memberships to return. The service might return fewer than this value. If unspecified, at most 100 spaces are returned. The maximum value is 1,000; values above 1,000 are automatically changed to 1,000.
  • pageToken: A page token, received from a previous list spaces 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.
  • filter: A query filter. Requires user authentication. For supported query details, see the spaces.members.list method.