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
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 Cloud 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.
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 Cloud 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.
Java
- 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 Java Cloud 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.
Apps Script
- 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.
- Create a standalone Apps Script project, and turn on the Advanced Chat Service.
- 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
SetUpSpace()
method. - Pass
space
as an instance ofSpace
with all the necessary fields such asdisplayName
orspaceType
. - Pass
memberships
as an array ofMembership
instances. For each instance:- Specify
users/{user}
to add a human user as a space member, 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
. - Specify
groups/{group}
to add a group as a space member, 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.
- Specify
To create a DM between the calling user and another human user, specify a membership of the human user in your request.
To create a DM between the calling user and the calling app, set
space.singleUserBotDm
to true
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 one membership to the space for two human users (the authenticated user and one other user).
Node.js
Python
Java
Apps Script
To run the sample, replace the following:
DISPLAY_NAME
: the display name of the new space.USER_NAME
: the ID of the other user to include a membership for.
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.