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.
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.
- Python 3.6 or greater
- The pip package management tool
- The latest Google client libraries. To install or update them,
run the following command in your command-line interface:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- 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.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file (
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.
- Node.js 14 or greater
- The npm package management tool
- The latest Google client libraries. To install or update them,
run the following command in your command-line interface:
npm install @google-cloud/local-auth @googleapis/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.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file (
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
method on themembership
resource. - Set
parent
to the resource name of the space in which to create membership. - Set
member
tousers/{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
ispeople/123456789
, then setmembership.member.name
tousers/123456789
. - The ID for the user in the Directory API.
- The user's email address. For example,
users/222larabrown@gmail.com
orusers/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 ID for the
person
in the People API. For example, if the People API
person
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 thespaces.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 thespaces.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
method on themembership
resource. - Set
parent
to the resource name of the space in which to create membership. - Set
groupMember
togroups/{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 namegroups/123456789
, then setmembership.groupMember.name
togroups/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 thespaces.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 thespaces.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 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 themembership
resource. - Set
parent
to the resource name of the space in which to create membership. - Set
member
tousers/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 thespaces.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 thespaces.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.
Related topics
- Get details about a user's or Chat app's membership.
- List members in a space.
- Update a user's membership in a Google Chat space.
- Remove a user or Chat app from a space.