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 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 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
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()
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 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
totrue
.
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 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.