Set up a space

This guide explains how to use setup method on the Space resource of the Google Chat API to set up a Google Chat space. Setting up a space creates a space and adds specified users to it.

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.

When setting up a space, consider the following:

  • The calling (authenticated) user is automatically added to the space, so you don't need to specify the user's membership in the request.
  • When creating a direct message (DM), if a DM exists between two users, then the DM is returned. Otherwise, a DM is created.
  • You can't set up spaces with threaded replies or add people outside of your Google Workspace.

Prerequisites

Python

  • 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. Setting up a space requires User authentication with the chat.spaces.create or chat.spaces authorization scope.

Set up a space

To set up a space, pass the following in your request:

  • Specify the chat.spaces.create or chat.spaces authorization scope.
  • Call the setup method on the Space resource.
  • To add a human user as a space member, specify users/{user}, where {user} is either the {person_id} for the person from the People API, or the ID of a user in the Directory API. For example, if the People API person resourceName is people/123456789, you can add the user to the space by including a membership with users/123456789 as the member.name.
  • To create a DM between the calling user and another human user, specify the membership of the human user in your request.
  • To create a DM between the calling user and the calling app, set Space.singleUserBotDm to true and don't specify any memberships. You can only use this method to set up a DM with the calling app. To add the calling app as a member of a space or a existing DM between two human users, see create a membership.

The following example creates a named space and creates memberships to the space for three human users, the authenticated user and two other specified users:

Python

  1. In your working directory, create a file named chat_space_setup.py.

  2. Include the following code in chat_space_setup.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.create"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then sets up a Chat space by creating a space and adding members.
    '''

    # 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().setup(

      # Details about the space to set up.
      body = {

        # Attributes of the space to set up, like space type and display name.
        'space': {

            # To set up a named space, set spaceType to SPACE.
            'spaceType': 'SPACE',

            # The user-visible name of the space
            'displayName': 'API-setup'
        },

        # The people and app to add to the space.
        #
        # The authenticated user is automatically added to the space,
        # and doesn't need to be specified in the memberships array.
        'memberships': [
            {
              'member': {
                'name':'users/123456789',
                'type': 'HUMAN'
              }
            },
            {
              'member': {
                'name':'users/987654321',
                'type': 'HUMAN'
              }
            }
        ]
      }

      ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

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

    python3 chat_space_setup.py

A named chat space with three human users including the authenticated user is set up.

To go to the space, use the space's resource ID to build the space's URL. You can get the resource ID from the space name in the Google Chat response body. For example, if your space's name is spaces/1234567, you can go to the space using the following URL: https://mail.google.com/chat/u/0/#chat/space/1234567.