List spaces

This guide explains how to list spaces with the Google Chat API. Listing spaces returns a paginated, filterable list of spaces.

Listing spaces with app authentication lists spaces that the Chat app has access to. Listing spaces with User authentication lists spaces that the authenticated user has access to.

Prerequisites

Python

Python 3.6 or greater
The pip package management tool
The Google client libraries for Python. To install them, run the following command in your command-line interface:
```
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
```
A published Chat app. To create and publish a Chat app, see Build a Google Chat app.
Authorization configured for the Chat app. Listing spaces supports both of the following authentication methods:
- User authentication with the chat.spaces.readonly or chat.spaces authorization scope.
- App authentication with the chat.bot authorization scope.

List spaces with user authentication

To list spaces in Google Chat, pass the following in your request:

With user authentication, specify the chat.spaces.readonly or chat.spaces authorization scope.
Call the list method on the Space resource.

The following example lists named spaces and group chats (but not direct messages, which are filtered out) visible to the authenticated user:

Python

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

Include the following code in chat_space_list.py:

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# 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.spaces.readonly"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then lists named spaces and group chats (but not direct messages)
    visible to the authenticated user.
    '''

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

          # An optional filter that returns named spaces or unnamed group chats,
          # but not direct messages (DMs).
          filter='spaceType = "SPACE" OR spaceType = "GROUP_CHAT"'

      ).execute()

    # Prints the returned list of spaces.
    print(result)

if __name__ == '__main__':
    main()

In your working directory, build and run the sample:
```
python3 chat_space_list.py
```

The Chat API returns a paginated array of named spaces and group chats.

List spaces with app authentication

To list spaces in Google Chat, pass the following in your request:

With app authentication, specify the chat.bot authorization scope.
Call the list method on the Space resource.

The following example lists named spaces and group chats (but not direct messages) visible to the Chat app:

Python

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

Include the following code in chat_space_list_app.py:

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

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

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

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

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

        # An optional filter that returns named spaces or unnamed
        # group chats, but not direct messages (DMs).
        filter='spaceType = "SPACE" OR spaceType = "GROUP_CHAT"'

    ).execute()

print(result)

In your working directory, build and run the sample:
```
python3 chat_space_list_app.py
```

The Chat API returns a paginated array of spaces.

Customize pagination or filter the list

To asynchronously list spaces in Google Chat, pass the following optional query parameters to customize pagination of or filter listed spaces:

pageSize: The maximum number of spaces 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.list method.