Set up a space

This guide explains how to set up a space with the Google Chat API. Setting up a space creates a space and adds specified users to it. You can set up the following types of spaces:

A named space where people send messages, share files, and collaborate.
An unnamed group chat between three or more people.
A direct message conversation between two humans, or a human and the Chat app calling the Chat API.

Prerequisites

Python

Python 3.6 or greater
The pip package management tool
The Google client libraries for Python. To install 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

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.

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][/chat/api/reference/rest/v1/spaces.members/create].

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

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

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()

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.