Invite or add a user or a 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 or a 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.

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

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 membership requires User authentication with the chat.memberships or chat.memberships.app authorization scope.

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 method 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 create membership for, and is either:
    • 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

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

  2. Include the following code in chat_membership_user_create.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.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()

  3. 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.

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

    python3 chat_membership_user_create.py

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

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 method 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

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

  2. Include the following code in chat_membership_app_create.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.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()

  3. 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.

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

    python3 chat_membership_app_create.py

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