Create a space

This guide explains how to use the create method on the Space resource of the Google Chat API to create a named space.

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.

A named space is a place where people send messages, share files, and collaborate. Named spaces can include Chat apps. Named spaces include extra features that unnamed group conversations and direct messages don't have, such as space managers who can apply administrative settings, descriptions, and add or remove people and apps. After creating a named space, the only member of the space is the authenticated user. The space doesn't include other people or apps; not even the Chat app that creates it. To add people, create memberships in the space by calling the create method on the Member resource. To learn how, see Create a membership.

To create a named space with multiple members—an unnamed group chat between three or more people, or a direct message conversation between two people, or a person and the Chat app calling the Chat API—set up a space instead.

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

Create a named space

To create a named space, pass the following in your request:

  • Specify the chat.spaces.create or chat.spaces authorization scope.
  • Call the create method on the Space resource.
  • Set spaceType to SPACE.
  • Set displayName to the user-visible name of the space. In the following example, displayName is set to API-made.
  • Optionally, set other space attributes, like spaceDetails (a user-visible description and set of guidelines for the space).

Here's how to create a named space:

Python

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

  2. Include the following code in chat_space_create_named.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 creates a Chat space.
    '''

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

      # Details about the space to create.
      body = {

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

        # The user-visible name of the space.
        'displayName': 'API-made'
      }

      ).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_create_named.py

A named space is created. To navigate to the space, use the space's resource ID to build the space's URL. You can find 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 navigate to the space using the following URL: https://mail.google.com/chat/u/0/#chat/space/1234567.