Update a space

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.

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.



  • Python 3.6 or greater
  • The pip package management tool
  • The latest Google client libraries for Python. To install or update 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. Updating a space requires User authentication with the chat.spaces authorization scope.

Update a space

To update an existing space in Google Chat, pass the following in your request:

  • Specify the chat.spaces authorization scope.
  • Call the patch method on the Space resource, and pass the name of the space to update, as well as an updateMask and a body that specifies the updated space attributes.
  • The updateMask specifies the aspects of the space to update, and includes the following:
    • displayName: Updates the user-readable name of the space displayed in the Google Chat UI. Only supports changing the display name of a space with the SPACE type, or when also including the spaceType mask to change a GROUP_CHAT space type to SPACE. Trying to update the display name of a GROUP_CHAT or a DIRECT_MESSAGE space results in an invalid argument error.
    • spaceType: Updates the type of space, but only supports changing a GROUP_CHAT space type to SPACE. Include displayName together with spaceType in the update mask and ensure that the specified space has a non-empty displayName and the SPACE space type. If the existing space already has the SPACE type, including the spaceType mask and the SPACE type in the specified space when updating the display name is optional . Trying to update the space type in other ways results in an invalid argument error.
    • spaceDetails: Details about the space including description and rules.
    • spaceHistoryState: Supports turning history on or off for the space if the organization lets users change their history setting. Mutually exclusive with all other field paths.

Here's how to update the spaceDetails of an existing space:


  1. In your working directory, create a file named chat_space_update.py.
  2. Include the following code in chat_space_update.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"]
    def main():
        Authenticates with Chat API via user credentials,
        then updates the specified space description and guidelines.
        # 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().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.
            'spaceDetails': {
              'description': 'This description was updated with Chat API!',
              'guidelines': 'These guidelines were updated with Chat API!'
        # Prints details about the created membership.
    if __name__ == '__main__':
  3. In the code, replace SPACE with a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.

  4. In your working directory, build and run the sample:

    python3 chat_space_update.py

The Google Chat API returns an instance of the Space resource reflecting the updates.