Invite or add a user, Google Group, or Google Chat app to a space

This guide explains how to use the create() method on the membership resource of the Google Chat API to invite or add a user, Google Group, or Chat app to a space also known as creating a membership. When creating a membership, if the specified member has their auto-accept policy turned off, then they're invited, and must accept the space invitation before joining. Otherwise, creating a membership adds the member directly to the specified space.

If you're a Google Workspace administrator, you can add users, Google Groups, or Chat apps to any space in your Google Workspace organization.

The Membership resource represents whether a human user or Google Chat app is invited to, part of, or absent from a space.

Prerequisites

Python

A Business or Enterprise Google Workspace account with access to Google Chat.

Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Python Google API Client Library.
- Create OAuth client ID credentials for a desktop application. To run the sample in this guide, save the credentials as a JSON file named client_secrets.json to your local directory.
Choose an authorization scope that supports user authentication.

Node.js

A Business or Enterprise Google Workspace account with access to Google Chat.

Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Node.js Google API Client Library.
- Create OAuth client ID credentials for a desktop application. To run the sample in this guide, save the credentials as a JSON file named client_secrets.json to your local directory.
Choose an authorization scope that supports user authentication.

Invite or add a user to a space

To invite or add a user to a space, pass the following in your request:

Specify the chat.memberships authorization scope.
Call the create() on the membership resource.
Set parent to the resource name of the space in which to create membership.
Set member to users/{user} where {user} is the person that you want to add to the space. To specify the Chat user, replace {user} with any of the following:
- The ID for the person in the People API. For example, if the People API person resourceName is people/123456789, then set membership.member.name to users/123456789.
- The ID for the user in the Directory API.
- The user's email address. For example, users/222larabrown@gmail.com or users/larabrown@cymbalgroup.com. If the user uses a Google Account or belongs to a different Google Workspace organization, you must use their email address.

The following example adds a user to a space:

Python

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

Include the following code in chat_membership_user_create.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.memberships"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then adds a user to a Chat space by creating a membership.
    '''

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

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which user the membership is for.
        body = {
          'member': {
            'name':'users/USER',
            'type': 'HUMAN'
          }
        }

    ).execute()

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

if __name__ == '__main__':
    main()

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
- USER: a user ID.
In your working directory, build and run the sample:
```
python3 chat_membership_user_create.py
```

Node.js

In your working directory, create a file named add-user-to-space.js.

Include the following code in add-user-to-space.js:

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

/**
* Adds the user to the Chat space.
* @return {!Promise<!Object>}
*/
async function addUserToSpace() {
  const scopes = [
    'https://www.googleapis.com/auth/chat.memberships',
  ];

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

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

  return await chatClient.spaces.members.create({
    parent: 'spaces/SPACE',
    requestBody: {member: {name: 'users/USER', type: 'HUMAN'}}
  });
}

addUserToSpace().then(console.log);

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
- USER: a user ID.
In your working directory, run the sample:
```
node add-user-to-space.js
```

The Chat API returns an instance of membership that details the user membership that was created.

Invite or add a Google Group to a space

To invite or add a Google Group to a space, pass the following in your request:

Specify the chat.memberships authorization scope.
Call the create() on the membership resource.
Set parent to the resource name of the space in which to create membership.
Set groupMember to 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 direct message, but only to a named space. The following example adds a group to a named space:

Python

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

Include the following code in chat_membership_group_create.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.memberships"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then adds a group to a Chat space by creating a membership.
    '''

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

        # The named space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which group the membership is for.
        body = {
          'groupMember': {
            'name':'groups/GROUP',
          }
        }

    ).execute()

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

if __name__ == '__main__':
    main()

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
- GROUP: a group ID.
In your working directory, build and run the sample:
```
python3 chat_membership_group_create.py
```

Node.js

In your working directory, create a file named add-group-to-space.js.

Include the following code in add-group-to-space.js:

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

/**
* Adds the group to the Chat space.
* @return {!Promise<!Object>}
*/
async function addUserToSpace() {
  const scopes = [
    'https://www.googleapis.com/auth/chat.memberships',
  ];

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

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

  return await chatClient.spaces.members.create({
    parent: 'spaces/SPACE',
    requestBody: {groupMember: {name: 'groups/GROUP'}}
  });
}

addUserToSpace().then(console.log);

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
- GROUP: a group ID.
In your working directory, run the sample:
```
node add-group-to-space.js
```

The Chat API returns an instance of membership that details the group membership that was created.

Add users or Google Groups to a space as a Google Workspace administrator

If you're a Google Workspace administrator, you can call the create() method to add users, Google Groups, or Chat apps to any space in your Google Workspace organization.

To call this method as a Google Workspace administrator, do the following:

Call the method using user authentication, and specify an authorization scope that supports calling the method using administrator privileges.
In your request, specify the query parameter useAdminAccess to true.

For more information and examples, see Manage Google Chat spaces as a Google Workspace administrator.

Add a Chat app to a space

A Chat app can't add another app as a member to a space. To add a Chat app to a space or a direct message between two human users, pass the following in your request:

Specify the chat.memberships.app authorization scope.
Call the create() on the membership resource.
Set parent to the resource name of the space in which to create membership.
Set member to users/app; an alias that represents the app calling the Chat API.

The following example adds a Chat app to a space:

Python

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

Include the following code in chat_membership_app_create.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.memberships.app"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then adds the Chat app to 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().members().create(

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Set the Chat app as the entity that gets added to the space.
        # 'app' is an alias for the Chat app calling the API.
        body = {
            'member': {
              'name':'users/app',
              'type': 'BOT'
            }
        }

    ).execute()

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

if __name__ == '__main__':
    main()

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.
In your working directory, build and run the sample:
```
python3 chat_membership_app_create.py
```

Node.js

In your working directory, create a file named add-app-to-space.js.

Include the following code in add-app-to-space.js:

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

/**
* Adds the app to the Chat space.
* @return {!Promise<!Object>}
*/
async function addAppToSpace() {
  const scopes = [
    'https://www.googleapis.com/auth/chat.memberships.app',
  ];

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

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

  return await chatClient.spaces.members.create({
    parent: 'spaces/SPACE',
    requestBody: {member: {name: 'users/app', type: 'BOT'}}
  });
}

addAppToSpace().then(console.log);

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.
In your working directory, run the sample:
```
node add-app-to-space.js
```

The Chat API returns an instance of membership that details the app membership that was created.

Invite or add a user, Google Group, or Google Chat app to a space

Prerequisites

Python

Node.js

Invite or add a user to a space

Python

Node.js

Invite or add a Google Group to a space

Python

Node.js

Add users or Google Groups to a space as a Google Workspace administrator

Add a Chat app to a space

Python

Node.js

Related topics