List members in a space

This guide explains how to use the list() method on the membership resource of the Google Chat API to list members 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.
  • Listing memberships as a Google Workspace administrator with user authentication using administrator privileges lists memberships in all spaces in your Google Workspace organization.

The Membership resource represents whether a human user or Google Chat app is invited to, part of, or absent from a space.

Prerequisites

Python

List members in a space with user authentication

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

The following example lists Google Group, human, and app members visible to the authenticated user.

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 Google Group, human, and app members 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',

        # Set this parameter to list Google Groups.
        showGroups = 'true'

    ).execute()

    # Prints the list of memberships.
    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 Google Group, human, and app members from the specified space.

List members 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.

List members as a Google Workspace administrator

If you're a Google Workspace administrator, you can call the list() method to list memberships for any space in your Google Workspace organization. The Chat API only returns memberships about users—both internal and external—or Google Groups from your organization, and therefore omits memberships for any Chat apps.

To call this method as a Google Workspace administrator, do the following:

  • Call the method using user authentication, and specify an authorization scope that supports calling the method using administrator privileges.
  • In your request, specify the following query parameters:
    • Set useAdminAccess to true.
    • To return only users, set the filter for member.type equal to HUMAN.
    • To return users and groups, set the filter for member.type not equal to BOT AND showGroups equal to true.

For more information and examples, see Manage Google Chat spaces as a Google Workspace administrator.

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 more than 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.