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
- 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.
Set up a space
To set up a space, pass the following in your request:
- Specify the
chat.spaces.create
orchat.spaces
authorization scope. - Call the
setup
method on theSpace
resource. - To add a human user as a space member, specify
users/{user}
, where{user}
is either the{person_id}
for theperson
from the People API, or the ID of auser
in the Directory API. For example, if the People API personresourceName
ispeople/123456789
, you can add the user to the space by including a membership withusers/123456789
as themember.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 namegroups/123456789
, then setmembership.groupMember.name
togroups/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
totrue
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
- In your working directory, create a file named
chat_space_setup.py
. 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()
In your working directory, build and run the sample:
python3 chat_space_setup.py
Node.js
- In your working directory, create a file named
setup-space.js
. 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);
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
.
Related topics
- Create a space.
- Get details about a space.
- List spaces.
- Update a space.
- Delete a space.
- Find a direct message space.
- Make a space discoverable to specific users.