--- title: "POST /v1/spaces:setup" method: POST path: "/v1/spaces:setup" tags: ["spaces"] --- # POST /v1/spaces:setup `POST /v1/spaces:setup` Creates a space and adds specified users to it. The calling user is automatically added to the space, and shouldn't be specified as a membership in the request. For an example, see [Set up a space with initial members](https://developers.google.com/workspace/chat/set-up-spaces). To specify the human members to add, add memberships with the appropriate `membership.member.name`. To add a human user, use `users/{user}`, where `{user}` can be the email address for the user. For users in the same Workspace organization `{user}` can also be the `id` for the person from the People API, or the `id` for the user in the Directory API. For example, if the People API Person profile ID for `user@example.com` is `123456789`, you can add the user to the space by setting the `membership.member.name` to `users/user@example.com` or `users/123456789`. To specify the Google groups to add, add memberships with the appropriate `membership.group_member.name`. To add or invite a Google group, use `groups/{group}`, where `{group}` is the `id` for the group from the Cloud Identity Groups API. For example, you can use [Cloud Identity Groups lookup API](https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup) to retrieve the ID `123456789` for group email `group@example.com`, then you can add the group to the space by setting the `membership.group_member.name` to `groups/123456789`. Group email is not supported, and Google groups can only be added as members in named spaces. For a named space or group chat, if the caller blocks, or is blocked by some members, or doesn't have permission to add some members, then those members aren't added to the created space. To create a direct message (DM) between the calling user and another human user, specify exactly one membership to represent the human user. If one user blocks the other, the request fails and the DM isn't created. 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 [Invite or add a user or app to a space](https://developers.google.com/workspace/chat/create-members). If a DM already exists between two users, even when one user blocks the other at the time a request is made, then the existing DM is returned. Spaces with threaded replies aren't supported. If you receive the error message `ALREADY_EXISTS` when setting up a space, try a different `displayName`. An existing space within the Google Workspace organization might already use this display name. Requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user) with one of the following [authorization scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes): - `https://www.googleapis.com/auth/chat.spaces.create` - `https://www.googleapis.com/auth/chat.spaces` ## Request body - SetUpSpaceRequest — Request to create a space and add specified users to it. - `space` Space — A space in Google Chat. Spaces are conversations between two or more users or 1:1 messages between a user and a Chat app. - `type` 'TYPE_UNSPECIFIED' | 'ROOM' | 'DM' — Output only. Deprecated: Use `space_type` instead. The type of a space. - `externalUserAllowed` boolean — Optional. Immutable. Whether this space permits any Google Chat user as a member. Input when creating a space in a Google Workspace organization. Omit this field when creating spaces in the following conditions: * The authenticated user uses a consumer account (unmanaged user account). By default, a space created by a consumer account permits any Google Chat user. For existing spaces, this field is output only. - `permissionSettings` PermissionSettings — [Permission settings](https://support.google.com/chat/answer/13340792) that you can specify when updating an existing named space. To set permission settings when creating a space, specify the `PredefinedPermissionSettings` field in your request. - `manageMembersAndGroups` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `toggleHistory` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `replyMessages` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `modifySpaceDetails` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `useAtMentionAll` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `postMessages` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `manageWebhooks` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `manageApps` PermissionSetting — Represents a space permission setting. - `membersAllowed` boolean — Optional. Whether basic space members (`ROLE_MEMBER`) have this permission. - `assistantManagersAllowed` boolean — Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission. - `managersAllowed` boolean — Optional. Whether space owners (`ROLE_MANAGER`) have this permission. - `spaceThreadingState` 'SPACE_THREADING_STATE_UNSPECIFIED' | 'THREADED_MESSAGES' | 'GROUPED_MESSAGES' | 'UNTHREADED_MESSAGES' — Output only. The threading state in the Chat space. - `createTime` string, google-datetime — Optional. Immutable. For spaces created in Chat, the time the space was created. This field is output only, except when used in import mode spaces. For import mode spaces, set this field to the historical timestamp at which the space was created in the source in order to preserve the original creation time. Only populated in the output when `spaceType` is `GROUP_CHAT` or `SPACE`. - `singleUserBotDm` boolean — Optional. Whether the space is a DM between a Chat app and a single human. - `name` string — Identifier. Resource name of the space. Format: `spaces/{space}` Where `{space}` represents the system-assigned ID for the space. You can obtain the space ID by calling the [`spaces.list()`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/list) method or from the space URL. For example, if the space URL is `https://mail.google.com/mail/u/0/#chat/space/AAAAAAAAA`, the space ID is `AAAAAAAAA`. - `threaded` boolean — Output only. Deprecated: Use `spaceThreadingState` instead. Whether messages are threaded in this space. - `spaceDetails` SpaceDetails — Details about the space including description and rules. - `description` string — Optional. A description of the space. For example, describe the space's discussion topic, functional purpose, or participants. Supports up to 150 characters. - `guidelines` string — Optional. The space's rules, expectations, and etiquette. Supports up to 5,000 characters. - `importMode` boolean — Optional. Whether this space is created in `Import Mode` as part of a data migration into Google Workspace. While spaces are being imported, they aren't visible to users until the import is complete. Creating a space in `Import Mode`requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user). - `spaceType` 'SPACE_TYPE_UNSPECIFIED' | 'SPACE' | 'GROUP_CHAT' | 'DIRECT_MESSAGE' — Optional. The type of space. Required when creating a space or updating the space type of a space. Output only for other usage. - `importModeExpireTime` string, google-datetime — Output only. The time when the space will be automatically deleted by the system if it remains in import mode. Each space created in import mode must exit this mode before this expire time using `spaces.completeImport`. This field is only populated for spaces that were created with import mode. - `customer` string — Optional. Immutable. The customer id of the domain of the space. Required only when creating a space with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) and `SpaceType` is `SPACE`, otherwise should not be set. In the format `customers/{customer}`, where `customer` is the `id` from the [Admin SDK customer resource](https://developers.google.com/admin-sdk/directory/reference/rest/v1/customers). Private apps can also use the `customers/my_customer` alias to create the space in the same Google Workspace organization as the app. This field isn't populated for direct messages (DMs) or when the space is created by non-Google Workspace users. - `spaceUri` string — Output only. The URI for a user to access the space. - `spaceHistoryState` 'HISTORY_STATE_UNSPECIFIED' | 'HISTORY_OFF' | 'HISTORY_ON' — Optional. The message history state for messages and threads in this space. - `accessSettings` AccessSettings — Represents the [access setting](https://support.google.com/chat/answer/11971020) of the space. - `accessState` 'ACCESS_STATE_UNSPECIFIED' | 'PRIVATE' | 'DISCOVERABLE' — Output only. Indicates the access state of the space. - `accessPermissionSettings` AccessPermissionSettings — Access permission settings for a space. - `discoverSpaceSetting` AccessPermissionSetting — An access permission setting. - `principals` Principal[] — Optional. Unordered list. Allowed principals for this permission. - `audience` Audience — A target audience in Google Chat. A target audience represents a group of users within a Google Workspace organization, defined by an administrator. Target audiences are used to configure access and visibility settings for resources, such as making a space discoverable to a specific group of users. For more details, see [Target audiences](https://support.google.com/a/answer/9934697) and [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience). - … - `joinSpaceSetting` AccessPermissionSetting — An access permission setting. - `principals` Principal[] — Optional. Unordered list. Allowed principals for this permission. - `audience` Audience — A target audience in Google Chat. A target audience represents a group of users within a Google Workspace organization, defined by an administrator. Target audiences are used to configure access and visibility settings for resources, such as making a space discoverable to a specific group of users. For more details, see [Target audiences](https://support.google.com/a/answer/9934697) and [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience). - … - `audience` string — Optional. The resource name of the [target audience](https://support.google.com/a/answer/9934697) who can discover the space, join the space, and preview the messages in the space. If unset, only users or Google Groups who have been individually invited or added to the space can access it. For details, see [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience). Format: `audiences/{audience}` To use the default target audience for the Google Workspace organization, set to `audiences/default`. Reading the target audience supports: - [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user) - [App authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) with [administrator approval](https://support.google.com/a?p=chat-app-auth) with the `chat.app.spaces` scope. This field is not populated when using the `chat.bot` scope with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app). Setting the target audience requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user). - `lastActiveTime` string, google-datetime — Output only. Timestamp of the last message in the space. - `membershipCount` MembershipCount — Represents the count of memberships of a space, grouped into categories. - `joinedDirectHumanUserCount` integer — Output only. Count of human users that have directly joined the space, not counting users joined by having membership in a joined group. - `joinedGroupCount` integer — Output only. Count of all groups that have directly joined the space. - `displayName` string — Optional. The space's display name. Required when [creating a space](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create) with a `spaceType` of `SPACE`. If you receive the error message `ALREADY_EXISTS` when creating a space or updating the `displayName`, try a different `displayName`. An existing space within the Google Workspace organization might already use this display name. For direct messages, this field might be empty. Supports up to 128 characters. - `adminInstalled` boolean — Output only. For direct message (DM) spaces with a Chat app, whether the space was created by a Google Workspace administrator. Administrators can install and set up a direct message with a Chat app on behalf of users in their organization. To support admin install, your Chat app must feature direct messaging. - `predefinedPermissionSettings` 'PREDEFINED_PERMISSION_SETTINGS_UNSPECIFIED' | 'COLLABORATION_SPACE' | 'ANNOUNCEMENT_SPACE' — Optional. Input only. Predefined space permission settings, input only when creating a space. If the field is not set, a collaboration space is created. After you create the space, settings are populated in the `PermissionSettings` field. Setting predefined permission settings supports: - [App authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) with [administrator approval](https://support.google.com/a?p=chat-app-auth) with the `chat.app.spaces` or `chat.app.spaces.create` scopes. - [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user) - `requestId` string — Optional. A unique identifier for this request. A random UUID is recommended. Specifying an existing request ID returns the space created with that ID instead of creating a new space. Specifying an existing request ID from the same Chat app with a different authenticated user returns an error. - `memberships` Membership[] — Optional. The Google Chat users or groups to invite to join the space. Omit the calling user, as they are added automatically. The set currently allows up to 49 memberships (in addition to the caller). For human membership, the `Membership.member` field must contain a `user` with `name` populated (format: `users/{user}`) and `type` set to `User.Type.HUMAN`. You can only add human users when setting up a space (adding Chat apps is only supported for direct message setup with the calling app). You can also add members using the user's email as an alias for {user}. For example, the `user.name` can be `users/example@gmail.com`. To invite Gmail users or users from external Google Workspace domains, user's email must be used for `{user}`. For Google group membership, the `Membership.group_member` field must contain a `group` with `name` populated (format `groups/{group}`). You can only add Google groups when setting `Space.spaceType` to `SPACE`. Optional when setting `Space.spaceType` to `SPACE`. Required when setting `Space.spaceType` to `GROUP_CHAT`, along with at least two memberships. Required when setting `Space.spaceType` to `DIRECT_MESSAGE` with a human user, along with exactly one membership. Must be empty when creating a 1:1 conversation between a human and the calling Chat app (when setting `Space.spaceType` to `DIRECT_MESSAGE` and `Space.singleUserBotDm` to `true`). - `name` string — Identifier. Resource name of the membership, assigned by the server. Format: `spaces/{space}/members/{member}` - `member` User — A user in Google Chat. When returned as an output from a request, if your Chat app [authenticates as a user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), the output for a `User` resource only populates the user's `name` and `type`. - `isAnonymous` boolean — Output only. When `true`, the user is deleted or their profile is not visible. - `name` string — Resource name for a Google Chat user. Format: `users/{user}`. `users/app` can be used as an alias for the calling app bot user. For human users, `{user}` is the same user identifier as: - the `id` for the [Person](https://developers.google.com/people/api/rest/v1/people) in the People API. For example, `users/123456789` in Chat API represents the same person as the `123456789` Person profile ID in People API. - the `id` for a [user](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users) in the Admin SDK Directory API. - the user's email address can be used as an alias for `{user}` in API requests. For example, if the People API Person profile ID for `user@example.com` is `123456789`, you can use `users/user@example.com` as an alias to reference `users/123456789`. Only the canonical resource name (for example `users/123456789`) will be returned from the API. - `type` 'TYPE_UNSPECIFIED' | 'HUMAN' | 'BOT' — User type. - `displayName` string — Output only. The user's display name. - `domainId` string — Unique identifier of the user's Google Workspace domain. - `state` 'MEMBERSHIP_STATE_UNSPECIFIED' | 'JOINED' | 'INVITED' | 'NOT_A_MEMBER' — Output only. State of the membership. - `role` 'MEMBERSHIP_ROLE_UNSPECIFIED' | 'ROLE_MEMBER' | 'ROLE_MANAGER' | 'ROLE_ASSISTANT_MANAGER' — Optional. User's role within a Chat space, which determines their permitted actions in the space. This field can only be used as input in `UpdateMembership`. - `createTime` string, google-datetime — Optional. Immutable. The creation time of the membership, such as when a member joined or was invited to join a space. This field is output only, except when used to import historical memberships in import mode spaces. - `deleteTime` string, google-datetime — Optional. Immutable. The deletion time of the membership, such as when a member left or was removed from a space. This field is output only, except when used to import historical memberships in import mode spaces. - `groupMember` Group — A Google Group in Google Chat. - `name` string — Resource name for a Google Group. Represents a [group](https://cloud.google.com/identity/docs/reference/rest/v1/groups) in Cloud Identity Groups API. Format: groups/{group} - `affiliation` 'AFFILIATION_UNSPECIFIED' | 'INTERNAL' | 'EXTERNAL' | 'MANAGED_EXTERNAL' — Output only. A user's relationship to the Workspace organization that owns the space. In spaces owned by consumer accounts, the affiliation of all members is `EXTERNAL`. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/chat.md) · [All operations](https://skmtc.net/google/apis/chat/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/chat/versions/a57a778f1fcb/schema)