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, join, and view members of the space.

To specify the users in your organization that can discover, join, and view
members of 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 provide more granular
control over who can access the space and its information. 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](https://knowledge.workspace.google.com/admin/groups/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](https://support.google.com/a/answer/6043576) account with access to [Google Chat](https://workspace.google.com/products/chat/). Your account must have the [super administrator
  role](https://support.google.com/a/answer/2405986?sjid=1448018578843125834-NC#super_admin) 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](https://support.google.com/a/answer/9935192). To make an existing target audience available to Chat spaces, see [Set up space access for Chat](https://support.google.com/a/answer/12129901).
- You must call Google Chat API, with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).

## Get the target audience ID

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

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

   [Go to Target audiences](https://admin.google.com/ac/targetaudiences)
2. In the **Target audiences** table, click the **Name** field of the target
   audience.

3. 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`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create) or
[`setup`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/setup) method on the
`Space` resource. To update permissions for an existing space, use the
[`update`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/patch) 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, join, or view members of a space, include the
[`AccessSettings`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#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.
- **View membership** : Use `viewSpaceMembershipSetting` to define who can see the list of members in a space. When updating who can view space membership, `accessSettings.accessPermissionSettings.viewSpaceMembershipSetting` must be specified together with [`permissionSettings.viewSpaceMembership`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space.PermissionSettings) in both the `updateMask` and request body. When a target audience is configured in `viewSpaceMembershipSetting`, `viewSpaceMembership` must be granted to all members (`managersAllowed`, `assistantManagersAllowed`, and `membersAllowed` set to `true`).

The following example shows how to make a space discoverable to two target
audiences, joinable by one of them, and ensure all members and specified target
audiences can view the member list:

    {
      "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" } }
            ]
          },
          "viewSpaceMembershipSetting": {
            "principals": [
              { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_1" } },
              { "audience": { "name": "audiences/TARGET_AUDIENCE_ID_2" } }
            ]
          }
        }
      },
      "permissionSettings": {
        "viewSpaceMembership": {
          "managersAllowed": true,
          "assistantManagersAllowed": true,
          "membersAllowed": true
        }
      }
    }

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](https://developers.google.com/workspace/chat/space-target-audience#get-target-audience).
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](https://developers.google.com/workspace/chat/space-target-audience#make-space) instead.

Setting the `audience`
field is equivalent to specifying the target audience in `joinSpaceSetting`:

      "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](https://developers.google.com/workspace/chat/space-target-audience#get-target-audience).
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 or list spaces, the
[`AccessSettings`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#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`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#accesspermissionsettings)
field.

## Related topics

For details about target audiences, see the following guides:

- [Create a target audience](https://support.google.com/a/answer/9935192)
- [Set up sharing in Chat](https://support.google.com/a/answer/12129901)
- [Create spaces with different access levels](https://support.google.com/chat/answer/11971020)

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

- [Create a space](https://developers.google.com/workspace/chat/create-spaces)
- [Set up a space](https://developers.google.com/workspace/chat/set-up-spaces)
- [Update a space](https://developers.google.com/workspace/chat/update-spaces)