This guide explains how to use the
patch()
method on the Space
resource of the Google Chat API to update a space. Update a
space to change attributes about a space, like its user-visible display name,
description, and guidelines.
If you're a Google Workspace administrator, you can call the patch()
method
to update any existing space in your Google Workspace organization.
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.
Prerequisites
Node.js
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Node.js Cloud Client Library.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
client_secrets.json
to your local directory.
- Choose an authorization scope that supports user authentication.
- A Google Chat space. To create one using the Google Chat API, see Create a space. To create one in Chat, visit the Help Center documentation.
Python
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Python Cloud Client Library.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
client_secrets.json
to your local directory.
- Choose an authorization scope that supports user authentication.
- A Google Chat space. To create one using the Google Chat API, see Create a space. To create one in Chat, visit the Help Center documentation.
Java
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Java Cloud Client Library.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
client_secrets.json
to your local directory.
- Choose an authorization scope that supports user authentication.
- A Google Chat space. To create one using the Google Chat API, see Create a space. To create one in Chat, visit the Help Center documentation.
Apps Script
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Create a standalone Apps Script project, and turn on the Advanced Chat Service.
- Choose an authorization scope that supports user authentication.
- A Google Chat space. To create one using the Google Chat API, see Create a space. To create one in Chat, visit the Help Center documentation.
Update a space as a user
To update an existing space in Google Chat with user authentication, pass the following in your request:
- Specify the
chat.spaces
authorization scope. - Call the
UpdateSpace()
method. In your request, you specify the spacename
field, theupdateMask
field with one or more fields to update, and abody
with the updated space information.
You can update things like the display name, space type, history state, and more. To see all the fields you can update, see the reference documentation.
Here's how to update the displayName
field of an existing space:
Node.js
Python
Java
Apps Script
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 an instance of the
Space
reflecting the
updates.
Update a space as a Google Workspace administrator
If you're a Google Workspace administrator, you can call the
UpdateSpace()
method to update any space in your Google Workspace
organization.
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 query parameter
useAdminAccess
totrue
.
For more information and examples, see Manage Google Chat spaces as a Google Workspace administrator.
Update a space as a Chat app
App authentication requires one-time administrator approval.
To update an existing space in Google Chat with app authentication, pass the following in your request:
- Specify the
chat.app.spaces
authorization scope. With app authentication, you can only update spaces created by Chat apps. - Call the
patch
method on theSpace
resource. In your request, you specify the spacename
field, theupdateMask
field with one or more fields to update, and abody
with the updated space information.
You can update things like the display name, space type, history state, permission settings, and more. To see all the fields you can update, see the reference documentation.
Create an API key
To call a Developer Preview API method, you must use a non-public developer preview version of the API discovery document. To authenticate the request, you must pass an API key.
To create the API Key, open your app's Google Cloud project and do the following:
- In the Google Cloud console, go to Menu > APIs & Services > Credentials.
- Click Create credentials > API key.
- Your new API key is displayed.
- Click Copy to copy your API key for use in your app's code. The API key can also be found in the "API keys" section of your project's credentials.
- Click Restrict key to update advanced settings and limit use of your API key. For more details, see Applying API key restrictions.
Write a script that calls Chat API
Here's how to update the spaceDetails
field of an existing space:
Python
- In your working directory, create a file named
chat_space_update_app.py
. Include the following code in
chat_space_update_app.py
:from google.oauth2 import service_account from apiclient.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.app.spaces"] def main(): ''' Authenticates with Chat API using app authentication, then updates the specified space description and guidelines. ''' # Specify service account details. creds = ( service_account.Credentials.from_service_account_file('credentials.json') .with_scopes(SCOPES) ) # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY') # Use the service endpoint to call Chat API. result = chat.spaces().patch( # The space to update, and the updated space details. # # Replace {space} with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. name='spaces/SPACE', updateMask='spaceDetails', body={ 'spaceDetails': { 'description': 'This description was updated with Chat API!', 'guidelines': 'These guidelines were updated with Chat API!' } } ).execute() # Prints details about the updated space. print(result) if __name__ == '__main__': main()
In the code, replace the following:
API_KEY
: the API key you created to build the service endpoint for Chat API.SPACE
with a space name, which you can obtain from thespaces.list
method in the Chat API, or from a space's URL.
In your working directory, build and run the sample:
python3 chat_space_update_app.py
The Google Chat API returns an instance of the
Space
resource reflecting the
updates.
Related topics
- Get details about a space.
- List spaces.
- Delete a space.
- Set up a space.
- Find a direct message space.
- Make a space discoverable to specific users.