List members in a space

  • This guide details how to retrieve a list of memberships for a Google Chat space using the list() method, offering filtering and pagination options.

  • Authentication can be done as a user, a Chat app, or a Workspace administrator, each with varying access levels to space memberships.

  • Developers need a Google Workspace account, Google Cloud project, and client libraries (Node.js, Python, Java, or Apps Script) to utilize the API.

  • Code samples are provided for various programming languages demonstrating how to list memberships with user and app authentication.

  • Important considerations include using the correct space ID, understanding member types (Google Group, human, and app), and the impact of administrator privileges.

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

Node.js

Python

Java

Apps Script

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:

  • With user authentication, specify the chat.memberships.readonly or chat.memberships authorization scope.
  • Call the ListMemberships() method.
  • To list Google Groups, set the query parameter showGroups to true.

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

Node.js

chat/client-libraries/cloud/list-memberships-user-cred.js
import{createClientWithUserCredentials}from'./authentication-utils.js';
constUSER_AUTH_OAUTH_SCOPES=[
'https://www.googleapis.com/auth/chat.memberships.readonly',
];
// This sample shows how to list memberships with user credential
asyncfunctionmain(){
// Create a client
constchatClient=awaitcreateClientWithUserCredentials(
USER_AUTH_OAUTH_SCOPES,
);
// Initialize request argument(s)
constrequest={
// Replace SPACE_NAME here
parent:'spaces/SPACE_NAME',
// Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
// ROLE_MANAGER)
filter:'member.type = "HUMAN"',
};
// Make the request
constpageResult=chatClient.listMembershipsAsync(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_memberships_user_cred.py
fromauthentication_utilsimport create_client_with_user_credentials
fromgoogle.appsimport chat_v1 as google_chat
SCOPES = ["https://www.googleapis.com/auth/chat.memberships.readonly"]
# This sample shows how to list memberships with user credential
deflist_memberships_user_cred():
 # Create a client
 client = create_client_with_user_credentials(SCOPES)
 # Initialize request argument(s)
 request = google_chat.ListMembershipsRequest(
 # Replace SPACE_NAME here
 parent = 'spaces/SPACE_NAME',
 # Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
 # ROLE_MANAGER)
 filter = 'member.type = "HUMAN"',
 # Number of results that will be returned at once
 page_size = 100
 )
 # Make the request
 page_result = client.list_memberships(request)
 # Handle the response. Iterating over page_result will yield results and
 # resolve additional pages automatically.
 for response in page_result:
 print(response)
list_memberships_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListMembershipsUserCred.java
importcom.google.chat.v1.ChatServiceClient;
importcom.google.chat.v1.ListMembershipsRequest;
importcom.google.chat.v1.ListMembershipsResponse;
importcom.google.chat.v1.Membership;
// This sample shows how to list memberships with user credential.
publicclass ListMembershipsUserCred{
privatestaticfinalStringSCOPE=
"https://www.googleapis.com/auth/chat.memberships.readonly";
publicstaticvoidmain(String[]args)throwsException{
try(ChatServiceClientchatServiceClient=
AuthenticationUtils.createClientWithUserCredentials(
ImmutableList.of(SCOPE))){
ListMembershipsRequest.Builderrequest=ListMembershipsRequest.newBuilder()
// Replace SPACE_NAME here.
.setParent("spaces/SPACE_NAME")
// Filter membership by type (HUMAN or BOT) or role
// (ROLE_MEMBER or ROLE_MANAGER).
.setFilter("member.type = \"HUMAN\"")
// Number of results that will be returned at once.
.setPageSize(10);
// Iterating over results and resolve additional pages automatically.
for(Membershipresponse:
chatServiceClient.listMemberships(request.build()).iterateAll()){
System.out.println(JsonFormat.printer().print(response));
}
}
}
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list memberships with user credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.readonly'
 * referenced in the manifest file (appsscript.json).
 */
functionlistMembershipsUserCred(){
// Initialize request argument(s)
// TODO(developer): Replace SPACE_NAME here
constparent='spaces/SPACE_NAME';
// Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
// ROLE_MANAGER)
constfilter='member.type = "HUMAN"';
// Iterate through the response pages using page tokens
letresponsePage;
letpageToken=null;
do{
// Request response pages
responsePage=Chat.Spaces.Members.list(parent,{
filter:filter,
pageSize:10,
pageToken:pageToken
});
// Handle response pages
if(responsePage.memberships){
responsePage.memberships.forEach((membership)=>console.log(membership));
}
// Update the page token to the next one
pageToken=responsePage.nextPageToken;
}while(pageToken);
}

To run this sample, replace SPACE_NAME with the ID from the space's name field. You can obtain the ID by calling the ListSpaces() method or from the space's URL.

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:

Node.js

chat/client-libraries/cloud/list-memberships-app-cred.js
import{createClientWithAppCredentials}from'./authentication-utils.js';
// This sample shows how to list memberships with app credential
asyncfunctionmain(){
// Create a client
constchatClient=createClientWithAppCredentials();
// Initialize request argument(s)
constrequest={
// Replace SPACE_NAME here
parent:'spaces/SPACE_NAME',
// Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
// ROLE_MANAGER)
filter:'member.type = "HUMAN"',
};
// Make the request
constpageResult=chatClient.listMembershipsAsync(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_memberships_app_cred.py
fromauthentication_utilsimport create_client_with_app_credentials
fromgoogle.appsimport chat_v1 as google_chat
# This sample shows how to list memberships with app credential
deflist_memberships_app_cred():
 # Create a client
 client = create_client_with_app_credentials()
 # Initialize request argument(s)
 request = google_chat.ListMembershipsRequest(
 # Replace SPACE_NAME here
 parent = 'spaces/SPACE_NAME',
 # Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
 # ROLE_MANAGER)
 filter = 'member.type = "HUMAN"',
 # Number of results that will be returned at once
 page_size = 100
 )
 # Make the request
 page_result = client.list_memberships(request)
 # Handle the response. Iterating over page_result will yield results and
 # resolve additional pages automatically.
 for response in page_result:
 print(response)
list_memberships_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListMembershipsAppCred.java
importcom.google.chat.v1.ChatServiceClient;
importcom.google.chat.v1.ListMembershipsRequest;
importcom.google.chat.v1.ListMembershipsResponse;
importcom.google.chat.v1.Membership;
// This sample shows how to list memberships with app credential.
publicclass ListMembershipsAppCred{
publicstaticvoidmain(String[]args)throwsException{
try(ChatServiceClientchatServiceClient=
AuthenticationUtils.createClientWithAppCredentials()){
ListMembershipsRequest.Builderrequest=ListMembershipsRequest.newBuilder()
// Replace SPACE_NAME here.
.setParent("spaces/SPACE_NAME")
// Filter membership by type (HUMAN or BOT) or role
// (ROLE_MEMBER or ROLE_MANAGER).
.setFilter("member.type = \"HUMAN\"")
// Number of results that will be returned at once.
.setPageSize(10);
// Iterate over results and resolve additional pages automatically.
for(Membershipresponse:
chatServiceClient.listMemberships(request.build()).iterateAll()){
System.out.println(JsonFormat.printer().print(response));
}
}
}
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list memberships with app credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
functionlistMembershipsAppCred(){
// Initialize request argument(s)
// TODO(developer): Replace SPACE_NAME here
constparent='spaces/SPACE_NAME';
// Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
// ROLE_MANAGER)
constfilter='member.type = "HUMAN"';
// Iterate through the response pages using page tokens
letresponsePage;
letpageToken=null;
do{
// Request response pages
responsePage=Chat.Spaces.Members.list(parent,{
filter:filter,
pageSize:10,
pageToken:pageToken
},getHeaderWithAppCredentials());
// Handle response pages
if(responsePage.memberships){
responsePage.memberships.forEach((membership)=>console.log(membership));
}
// Update the page token to the next one
pageToken=responsePage.nextPageToken;
}while(pageToken);
}

To run this sample, replace SPACE_NAME with the ID from the space's name field. You can obtain the ID by calling the ListSpaces() method or from the space's URL.

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 ListMemberships() 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 ListMembershipsRequest 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 2025年10月13日 UTC.