Make a Google Chat space discoverable to specific users in a Google Workspace organization

Page Summary

This page guides Google Workspace admins on how to use the Google Chat API to share named spaces with specific users within their organization.
Target audiences are used to control which users can discover and join a space, replacing the need to invite individuals.
To share a space, the AccessSettings object in the Chat API request should contain the target audience ID within the audience field.
Prerequisites include a Business or Enterprise Google Workspace account with super admin privileges, an available target audience, and user authentication when calling the Chat API.
Admins can get the target audience ID from the Google Admin console under Directory > Target Audiences, then locate it within the URL of the specific target audience page.

This page explains how to use the Google Chat API to share a Google Chat space with specific users in a Google Workspace organization, so that they can discover and join the space.

To specify the users in your organization that can discover and join a space, you create target audiences. A target audience is a group of people—such as specific departments or the entire organization—that you can share a Chat space with, to improve the space's awareness and shareability. Target audiences also let you manage and customize space memberships rather than needing to invite individual users to a space. For more information, see About target audiences.

You can only make named spaces discoverable to target audiences. You can't share other space types, such as direct messages or group conversations, with target audiences.

Prerequisites

A Business or Enterprise Google Workspace account with access to Google Chat. Your account must have the super administrator role for your Google Workspace organization.
A target audience that's available for access in Chat. To create a target audience, see Create a target audience. To make an existing target audience available to Chat spaces, see Set up space access for Chat.
You must call Google Chat API, with user authentication.

Get the target audience ID

To get the ID of a target audience, do the following:

In the Google Admin console, go to Menu > Directory > Target audiences.

Go to Target audiences
In the Target audiences table, click the Name field of the target audience.
Find the target audience ID in the URL for the page. The URL format is https://admin.google.com/ac/targetaudiences/TARGET_AUDIENCE_ID, where TARGET_AUDIENCE_ID is the alphanumeric ID for your target audience.

In the next section, you use the target audience ID to either create a discoverable space or update an existing space to make it discoverable to the target audience.

Specify target audiences and granular permissions

To create a space with specific access permissions, use the create or setup method on the Space resource. To update permissions for an existing space, use the update method. Because only named spaces can be shared with target audiences, the space type (represented in the spaceType field) must be SPACE.

To specify who can discover or join a space, include the AccessSettings object in the Space resource. In the object, use the accessPermissionSettings field to specify one or more of the following permissions:

Discoverable: Use discoverSpaceSetting to define who can find the name and description of a space and browse for it within Google Chat. You can specify multiple target audiences for discovery.
Joinable: Use joinSpaceSetting to define who can join a space without an explicit invitation and preview the space message. Users who can join a space must also be able to discover it. Google Chat supports a single target audience for this permission.

The following example shows how to make a space discoverable to two target audiences and joinable by one of them:

  "accessSettings": {
    "accessPermissionSettings": {
      "discoverSpaceSetting": {
        "principals": [
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } },
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_2" } }
        ]
      },
      "joinSpaceSetting": {
        "principals": [
          { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } }
        ]
      }
    }
  }

Replace TARGET_AUDIENCE_ID_1 and TARGET_AUDIENCE_ID_2 with the ID of the target audience that you obtained in Get the target audience ID. To use the default Chat space share settings for your Google Workspace organization, replace with default.

For backward compatibility, use the `audience` field

For backward compatibility, you can continue to use the audience field to specify a single target audience that can join a space, but we recommend Specify target audiences and granular permissions instead.

Setting the audience field is equivalent to specifying the target audience in both joinSpaceSetting and discoverSpaceSetting:

  "accessSettings": {
    "audience": "audiences/TARGET_AUDIENCE_ID"
  }

Replace TARGET_AUDIENCE_ID with the ID of the target audience that you obtained in Get the target audience ID. To use the default Chat space share settings for your Google Workspace organization, replace with default.

Understand access settings in API responses

When you get spaces, the AccessSettings object in the response reflects the granular permissions set for the space.

The following fields in AccessSettings indicate a space's searchability and joining permissions:

accessState: Derived from discovery permissions (discoverSpaceSetting). If discovery is granted to one or more target audiences, this field is DISCOVERABLE. Otherwise, it's PRIVATE.
audience: Mapped specifically to join permissions (joinSpaceSetting). If a single target audience is granted join permission, this field contains the resource name of that target audience.

Discoverable space with no join audience

A space might be discoverable by a target audience but can't be joined directly (for example, if users must be explicitly invited to join).

In this case, the AccessSettings object has the following values:

accessState: DISCOVERABLE
audience: Omitted or null

If you see accessState set to DISCOVERABLE but audience is not present, it means the space can be discovered by the target audiences specified in discoverSpaceSetting, but it can only be joined by invitation. To see which target audiences can discover the space, check the accessPermissionSettings.discoverSpaceSetting field.

For details about target audiences, see the following guides:

For details on creating or updating spaces using the Chat API, see the following guides:

Make a Google Chat space discoverable to specific users in a Google Workspace organization Stay organized with collections Save and categorize content based on your preferences.