List spaces

  • This guide explains how to use the list() method to retrieve a paginated, filterable list of spaces within Google Chat using the Google Chat API.

  • Spaces in Google Chat can be direct messages, group chats, or named spaces for collaboration, and the spaces listed depend on the authentication method (app or user).

  • Code samples demonstrate how to list spaces using both user and app authentication, covering Node.js, Python, Java, and Apps Script.

  • The pageSize, pageToken, and filter parameters can be used to control pagination and refine the list of spaces returned by the API.

  • This guide also provides links to related topics such as creating, updating, and deleting spaces, as well as finding direct message spaces.

This guide explains how to use the list() method on the Space resource of the Google Chat API to list spaces. Listing spaces returns a paginated, filterable list of spaces.

The Space resource represents a place where people and Chat apps can send messages, share files, and collaborate. There are several types of spaces:

  • Direct messages (DMs) are conversations between two users or a user and a Chat app.
  • Group chats are conversations between three or more users and Chat apps.
  • Named spaces are persistent places where people send messages, share files, and collaborate.

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

Node.js

Python

Java

Apps Script

List spaces with user authentication

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

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

Node.js

chat/client-libraries/cloud/list-spaces-user-cred.js
import{createClientWithUserCredentials}from'./authentication-utils.js';
constUSER_AUTH_OAUTH_SCOPES=[
'https://www.googleapis.com/auth/chat.spaces.readonly',
];
// This sample shows how to list spaces with user credential
asyncfunctionmain(){
// Create a client
constchatClient=awaitcreateClientWithUserCredentials(
USER_AUTH_OAUTH_SCOPES,
);
// Initialize request argument(s)
constrequest={
// Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
filter:'space_type = "SPACE"',
};
// Make the request
constpageResult=chatClient.listSpacesAsync(request);
// Handle the response. Iterating over pageResult will yield results
// and resolve additional pages automatically.
forawait(constresponseofpageResult){
console.log(response);
}
}
awaitmain();

Python

chat/client-libraries/cloud/list_spaces_user_cred.py
fromauthentication_utilsimport create_client_with_user_credentials
fromgoogle.appsimport chat_v1 as google_chat
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.readonly"]
# This sample shows how to list spaces with user credential
deflist_spaces_with_user_cred():
 # Create a client
 client = create_client_with_user_credentials(SCOPES)
 # Initialize request argument(s)
 request = google_chat.ListSpacesRequest(
 # Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
 filter = 'space_type = "SPACE"',
 # Number of results that will be returned at once
 page_size = 100
 )
 # Make the request
 page_result = client.list_spaces(request)
 # Handle the response. Iterating over page_result will yield results and
 # resolve additional pages automatically.
 for response in page_result:
 print(response)
list_spaces_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListSpacesUserCred.java
importcom.google.chat.v1.ChatServiceClient;
importcom.google.chat.v1.ListSpacesRequest;
importcom.google.chat.v1.ListSpacesResponse;
importcom.google.chat.v1.Space;
// This sample shows how to list spaces with user credential.
publicclass ListSpacesUserCred{
privatestaticfinalStringSCOPE=
"https://www.googleapis.com/auth/chat.spaces.readonly";
publicstaticvoidmain(String[]args)throwsException{
try(ChatServiceClientchatServiceClient=
AuthenticationUtils.createClientWithUserCredentials(
ImmutableList.of(SCOPE))){
ListSpacesRequest.Builderrequest=ListSpacesRequest.newBuilder()
// Filter spaces by space type (SPACE or GROUP_CHAT or
// DIRECT_MESSAGE).
.setFilter("spaceType = \"SPACE\"")
// Number of results that will be returned at once.
.setPageSize(10);
// Iterate over results and resolve additional pages automatically.
for(Spaceresponse:
chatServiceClient.listSpaces(request.build()).iterateAll()){
System.out.println(JsonFormat.printer().print(response));
}
}
}
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list spaces with user credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.spaces.readonly'
 * referenced in the manifest file (appsscript.json).
 */
functionlistSpacesUserCred(){
// Initialize request argument(s)
// Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
constfilter='space_type = "SPACE"';
// Iterate through the response pages using page tokens
letresponsePage;
letpageToken=null;
do{
// Request response pages
responsePage=Chat.Spaces.list({
filter:filter,
pageSize:10,
pageToken:pageToken,
});
// Handle response pages
if(responsePage.spaces){
for(constspaceofresponsePage.spaces){
console.log(space);
}
}
// Update the page token to the next one
pageToken=responsePage.nextPageToken;
}while(pageToken);
}

The Chat API returns a paginated list of spaces.

List spaces with app authentication

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

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

Node.js

chat/client-libraries/cloud/list-spaces-app-cred.js
import{createClientWithAppCredentials}from'./authentication-utils.js';
// This sample shows how to list spaces with app credential
asyncfunctionmain(){
// Create a client
constchatClient=createClientWithAppCredentials();
// Initialize request argument(s)
constrequest={
// Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
filter:'space_type = "SPACE"',
};
// Make the request
constpageResult=chatClient.listSpacesAsync(request);
// Handle the response. Iterating over pageResult will yield results
// and resolve additional pages automatically.
forawait(constresponseofpageResult){
console.log(response);
}
}
awaitmain();

Python

chat/client-libraries/cloud/list_spaces_app_cred.py
fromauthentication_utilsimport create_client_with_app_credentials
fromgoogle.appsimport chat_v1 as google_chat
# This sample shows how to list spaces with app credential
deflist_spaces_app_cred():
 # Create a client
 client = create_client_with_app_credentials()
 # Initialize request argument(s)
 request = google_chat.ListSpacesRequest(
 # Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
 filter = 'space_type = "SPACE"',
 # Number of results that will be returned at once
 page_size = 100
 )
 # Make the request
 page_result = client.list_spaces(request)
 # Handle the response. Iterating over page_result will yield results and
 # resolve additional pages automatically.
 for response in page_result:
 print(response)
list_spaces_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListSpacesAppCred.java
importcom.google.chat.v1.ChatServiceClient;
importcom.google.chat.v1.ListSpacesRequest;
importcom.google.chat.v1.ListSpacesResponse;
importcom.google.chat.v1.Space;
// This sample shows how to list spaces with app credential.
publicclass ListSpacesAppCred{
publicstaticvoidmain(String[]args)throwsException{
try(ChatServiceClientchatServiceClient=
AuthenticationUtils.createClientWithAppCredentials()){
ListSpacesRequest.Builderrequest=ListSpacesRequest.newBuilder()
// Filter spaces by space type (SPACE or GROUP_CHAT or
// DIRECT_MESSAGE).
.setFilter("spaceType = \"SPACE\"")
// Number of results that will be returned at once.
.setPageSize(10);
// Iterate over results and resolve additional pages automatically.
for(Spaceresponse:
chatServiceClient.listSpaces(request.build()).iterateAll()){
System.out.println(JsonFormat.printer().print(response));
}
}
}
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list spaces with app credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
functionlistSpacesAppCred(){
// Initialize request argument(s)
// Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
constfilter='space_type = "SPACE"';
// Iterate through the response pages using page tokens
letresponsePage;
letpageToken=null;
do{
// Request response pages
responsePage=Chat.Spaces.list(
{
filter:filter,
pageSize:10,
pageToken:pageToken,
},
getHeaderWithAppCredentials(),
);
// Handle response pages
if(responsePage.spaces){
for(constspaceofresponsePage.spaces){
console.log(space);
}
}
// Update the page token to the next one
pageToken=responsePage.nextPageToken;
}while(pageToken);
}

The Chat API returns a paginated list of spaces.

Customize pagination or filter the list

To 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 higher 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. For supported query details, see the ListSpacesRequest reference.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026年07月22日 UTC.