Manage Google Chat spaces as a Google Workspace administrator

This page provides an overview of how Google Workspace administrators can use the Google Chat API to manage Google Chat spaces across their organization.

To manage Chat spaces, Google Workspace administrators can use the Space Management Tool in the Google Admin console or call the Google Chat API. By using the Chat API, administrators can create Google Chat apps that manage spaces at scale and automate their common or repeatable tasks.

What administrators can do with the Chat API

An administrator can perform management tasks based on their assigned administrator roles.

As a Google Workspace administrator, you can perform a number of management tasks with the Chat API, such as the following:

How to authenticate and authorize as a Google Workspace adminstrator

When using the Chat API for management tasks, administrators can authenticate and authorize requests by invoking administrator privileges or configuring domain-wide delegation of authority for an application's service account.

The following table describes the ways administrators can authenticate when using the Chat API.

User authentication Who calls the API method What users see in Chat
Administrator privileges Administrator with useAdminAccess=true

"The organization's administrator performed [an action]."

For example, "The organization's administrator changed Kiran B to space manager."

It does not identify the administrator user's name or user ID or the name of the Chat app.
Domain-wide delegation Service account on behalf of a user

"[User] performed [an action] via [app name]."

For example, "Sasha T renamed the space to Release Project Discussion."

The user who is being impersonated by the service is identified as having performed the action.

Use the Chat API for your organization

The examples in this section demonstrate how administrators use the Chat API when managing their organization's spaces and members with administrator privileges.

The following Chat API methods enable administrator privileges with useAdminAccess=true.

Manage users' space memberships

The following scenarios are ways that you, as a Google Workspace administrator, can manage the space membership of users in your organization with the Chat API.

Add users to spaces

Using spaces.members.create(), admins can add a user to any space in an organization.

Used in conjunction with spaces.search(), admins can add a user to a set of spaces determined by their search query. This can be useful when onboarding new employees to an organization; it allows administrators to automate a routine process.

Find users and remove them from spaces

Using spaces.members.get(), admins can determine if a user (internal or external to the organization) is a member of any space in the organization.

Used in conjunction with spaces.search(), admins can find all spaces that the user is a member of and then remove them from the spaces with spaces.members.delete(). This can be useful when employees move teams within an organization or offboarding employees who are no longer with the organization; it allows administrators to automate a routine process.

Promote users to space manager

Using spaces.members.patch(), admins can promote members of a space from ROLE_MEMBER to ROLE_MANAGER. Admins can also use spaces.members.patch() to move members from ROLE_MANAGER to ROLE_MEMBER.

Used in conjunction with spaces.search(), admins can find spaces that don't have a manager and then promote an existing member to ROLE_MANAGER with spaces.members.patch().

Find external members of a space

Using spaces.members.list(), admins can retrieve a list of members in a space, retrieve the user profiles from the organization's People API or Directory API, and then filter the results for those who are members of an external domain or organization. For more information, see How chat identifies users.

Audit and manage spaces

The following scenarios are ways that you, as a Google Workspace administrator, can audit and manage the spaces in your organization with the Chat API.

Find and delete inactive spaces

Unused Chat spaces can take up valuable storage space and create clutter in the user interface. Admins can use spaces.search() to find the inactive spaces and then spaces.delete() to delete them. For further guidance and a code sample, see Find and delete inactive Chat spaces.

Audit spaces in the organization

Using spaces.search(), admins can retrieve a list of all spaces in an organization with detailed information about each space's settings and metadata such as creation date, last activity date, number of members, status of history setting, and ability to invite external guests.

Export a list of spaces based on search criteria

Using spaces.search(), admins can retrieve a list of spaces that meet criteria specified in the query and export the results to a CSV file for analysis.

Find members of a space based on search criteria

Using spaces.members.list(), admins can retrieve a list of members for any space in the organization and analyze the results for specific criteria.

Find managers of a space

Using spaces.members.list(), admins can retrieve a list of members for a space that is filtered to MembershipState=ROLE_MANAGER.

To find all space managers in your organization, across all spaces, you can use spaces.search() to list them all. Then for each space in the list, use spaces.members.list to retrieve the managers.