Set up a space with initial members

This guide explains how to use the 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.
  • When creating a group chat, if none of the memberships provided in the request are successfully added to the group chat (for example, permission issue), then an empty group chat (including only the calling user) might be created.
  • You can't set up spaces with threaded replies or add people outside of your Google Workspace.
  • Duplicate memberships (including the calling user) provided in the request are filtered out instead of resulting in a request error.

Prerequisites

Python

Node.js

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 add a group as a space member, specify groups/{group}, where {group} is the group ID that you want to create membership for. The ID for the group can be retrieved using the Cloud Identity API. For example, if the Cloud Identity API returns a group with name groups/123456789, then set membership.groupMember.name to groups/123456789. Google Groups can't be added to a group chat or DM, but only to a named space.
  • 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 an existing DM between two human users, see create a membership.

The following example creates a named space and creates memberships to the space for one group and three human users (including 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:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.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.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 users and groups 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'
              }
            },
            {
              'groupMember': {
                'name': 'groups/11223344'
              }
            }
        ]
      }

      ).execute()

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

if __name__ == '__main__':
    main()

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

    python3 chat_space_setup.py

Node.js

  1. In your working directory, create a file named setup-space.js.

  2. Include the following code in setup-space.js:

    const chat = require('@googleapis/chat');
const {authenticate} = require('@google-cloud/local-auth');

/**
* Sets up a new Chat space with users.
* @return {!Promise<!Object>}
*/
async function setupSpace() {
  const scopes = [
    'https://www.googleapis.com/auth/chat.spaces.create',
  ];

  const authClient =
      await authenticate({scopes, keyfilePath: 'client_secrets.json'});

  const chatClient = await chat.chat({version: 'v1', auth: authClient});

  return await chatClient.spaces.setup({
    requestBody: {
      space: {
        spaceType: 'SPACE',
        displayName: 'API-made',
      },
      memberships: [
        {member: {name: 'users/123456789', type: 'HUMAN'}},
        {member: {name: 'users/987654321', type: 'HUMAN'}},
        {groupMember: {name: 'groups/11223344'}},
      ]
    }
  });
}

setupSpace().then(console.log);

  3. In your working directory, run the sample:

    node setup-space.js

A named chat space with one group and 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.