Google Chat V1 API - Class Google::Apps::Chat::V1::ChatService::Client (v0.7.0)

Format: spaces/{space}

Format: spaces/{space}

The memberType field must contain a user with the user.name and user.type fields populated. The server will assign a resource name and overwrite anything specified.

When a Chat app creates a membership relation for a human user, it must use certain authorization scopes and set specific values for certain fields:

• When authenticating as a user, the chat.memberships authorization scope is required.

• When authenticating as an app, the chat.app.memberships authorization scope is required. Authenticating as an app is available in Developer Preview.

• Set user.type to HUMAN, and set user.name with format 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 of 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.

Inviting users external to the Workspace organization that owns the space requires user authentication.

When a Chat app creates a membership relation for itself, it must authenticate as a user and use the chat.memberships.app scope, set user.type to BOT, and set user.name to users/app.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.memberships OAuth 2.0 scope.

Creating app memberships or creating memberships for users outside the administrator's Google Workspace organization isn't supported using admin access.

Format: spaces/{space}

When responding to user interactions, this field is ignored. For interactions within a thread, the reply is created in the same thread. Otherwise, the reply is created as a new thread.

The value for this field must meet the following requirements:

• Begins with client-. For example, client-custom-name is a valid custom ID, but custom-name is not.
• Contains up to 63 characters and only lowercase letters, numbers, and hyphens.
• Is unique within a space. A Chat app can't use the same custom ID for different messages.

For details, see Name a message.

Format: spaces/{space}/messages/{message}

If you receive the error message ALREADY_EXISTS, try a different displayName. An existing space within the Google Workspace organization might already use this display name.

The space name is assigned on the server so anything specified in this field will be ignored.

When deleting a human membership, requires the chat.memberships scope and spaces/{space}/members/{member} format. You can use the email as an alias for {member}. For example, spaces/{space}/members/example@gmail.com where example@gmail.com is the email of the Google Chat user.

When deleting an app membership, requires the chat.memberships.app scope and spaces/{space}/members/app format.

Format: spaces/{space}/members/{member} or spaces/{space}/members/app.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.memberships OAuth 2.0 scope.

Deleting app memberships in a space isn't supported using admin access.

Format: spaces/{space}/messages/{message}

If you've set a custom ID for your message, you can use the value from the clientAssignedMessageId field for {message}. For details, see Name a message.

Only applies when authenticating as a user. Has no effect when authenticating as a Chat app.

Format: spaces/{space}/messages/{message}/reactions/{reaction}

Format: spaces/{space}

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.delete OAuth 2.0 scope.

Format: users/{user}, where {user} is either 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 profile ID is 123456789, you can find a direct message with that person by using users/123456789 as the name. When authenticated as a user, you can use the email as an alias for {user}. For example, users/example@gmail.com where example@gmail.com is the email of the Google Chat user.

To get the app's own membership by using user authentication, you can optionally use spaces/{space}/members/app.

Format: spaces/{space}/members/{member} or spaces/{space}/members/app

You can use the user's email as an alias for {member}. For example, spaces/{space}/members/example@gmail.com where example@gmail.com is the email of the Google Chat user.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.memberships or chat.admin.memberships.readonly OAuth 2.0 scopes.

Getting app memberships in a space isn't supported when using admin access.

Format: spaces/{space}/messages/{message}

If you've set a custom ID for your message, you can use the value from the clientAssignedMessageId field for {message}. For details, see Name a message.

Format: spaces/{space}

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.spaces or chat.admin.spaces.readonly OAuth 2.0 scopes.

Format: spaces/{space}/spaceEvents/{spaceEvent}

Only supports getting read state for the calling user.

To refer to the calling user, set one of the following:

• The me alias. For example, users/me/spaces/{space}/spaceReadState.

• Their Workspace email address. For example, users/user@example.com/spaces/{space}/spaceReadState.

• Their user id. For example, users/123456789/spaces/{space}/spaceReadState.

Format: users/{user}/spaces/{space}/spaceReadState

Only supports getting read state for the calling user.

To refer to the calling user, set one of the following:

• The me alias. For example, users/me/spaces/{space}/threads/{thread}/threadReadState.

• Their Workspace email address. For example, users/user@example.com/spaces/{space}/threads/{thread}/threadReadState.

• Their user id. For example, users/123456789/spaces/{space}/threads/{thread}/threadReadState.

Format: users/{user}/spaces/{space}/threads/{thread}/threadReadState

Format: spaces/{space}

If unspecified, at most 100 memberships are returned.

The maximum value is 1000. If you use a value more than 1000, it's automatically changed to 1000.

Negative values return an INVALID_ARGUMENT error.

When paginating, all other parameters provided should match the call that provided the page token. Passing different values to the other parameters might lead to unexpected results.

You can filter memberships by a member's role (role) and type (member.type).

To filter by role, set role to ROLE_MEMBER or ROLE_MANAGER.

To filter by type, set member.type to HUMAN or BOT. You can also filter for member.type using the != operator.

To filter by both role and type, use the AND operator. To filter by either role or type, use the OR operator.

Either member.type = "HUMAN" or member.type != "BOT" is required when use_admin_access is set to true. Other member type filters will be rejected.

For example, the following queries are valid:

``` role = "ROLE_MANAGER" OR role = "ROLE_MEMBER" member.type = "HUMAN" AND role = "ROLE_MANAGER"

member.type != "BOT" ```

The following queries are invalid:

member.type = "HUMAN" AND member.type = "BOT" role = "ROLE_MANAGER" AND role = "ROLE_MEMBER"

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.

Currently requires user authentication.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires either the chat.admin.memberships.readonly or chat.admin.memberships OAuth 2.0 scope.

Listing app memberships in a space isn't supported when using admin access.

Format: spaces/{space}

If unspecified, at most 25 are returned.

The maximum value is 1000. If you use a value more than 1000, it's automatically changed to 1000.

Negative values return an INVALID_ARGUMENT error.

When paginating, all other parameters provided should match the call that provided the page token. Passing different values to the other parameters might lead to unexpected results.

You can filter messages by date (create_time) and thread (thread.name).

To filter messages by the date they were created, specify the create_time with a timestamp in RFC-3339 format and double quotation marks. For example, "2023-04-21T11:30:00-04:00". You can use the greater than operator > to list messages that were created after a timestamp, or the less than operator < to list messages that were created before a timestamp. To filter messages within a time interval, use the AND operator between two timestamps.

To filter by thread, specify the thread.name, formatted as spaces/{space}/threads/{thread}. You can only specify one thread.name per query.

To filter by both thread and date, use the AND operator in your query.

For example, the following queries are valid:

``` create_time > "2012-04-21T11:30:00-04:00"

create_time > "2012-04-21T11:30:00-04:00" AND thread.name = spaces/AAAAAAAAAAA/threads/123

create_time > "2012-04-21T11:30:00+00:00" AND

create_time < "2013-01-01T00:00:00+00:00" AND thread.name = spaces/AAAAAAAAAAA/threads/123

thread.name = spaces/AAAAAAAAAAA/threads/123 ```

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.

• ASC for ascending.

• DESC for descending.

The default ordering is create_time ASC.

Format: spaces/{space}/messages/{message}

A page token received from a previous list reactions call. Provide this to retrieve the subsequent page.

When paginating, the filter value should match the call that provided the page token. Passing a different value might lead to unexpected results.

You can filter reactions by emoji (either emoji.unicode or emoji.custom_emoji.uid) and user (user.name).

To filter reactions for multiple emojis or users, join similar fields with the OR operator, such as emoji.unicode = "🙂" OR emoji.unicode = "👍" and user.name = "users/AAAAAA" OR user.name = "users/BBBBBB".

To filter reactions by emoji and user, use the AND operator, such as emoji.unicode = "🙂" AND user.name = "users/AAAAAA".

If your query uses both AND and OR, group them with parentheses.

For example, the following queries are valid:

user.name = "users/\\{user}" emoji.unicode = "🙂" emoji.custom_emoji.uid = "\\{uid}" emoji.unicode = "🙂" OR emoji.unicode = "👍" emoji.unicode = "🙂" OR emoji.custom_emoji.uid = "\\{uid}" emoji.unicode = "🙂" AND user.name = "users/\\{user}" (emoji.unicode = "🙂" OR emoji.custom_emoji.uid = "\\{uid}") AND user.name = "users/\\{user}"

The following queries are invalid:

emoji.unicode = "🙂" AND emoji.unicode = "👍" emoji.unicode = "🙂" AND emoji.custom_emoji.uid = "\\{uid}" emoji.unicode = "🙂" OR user.name = "users/\\{user}" emoji.unicode = "🙂" OR emoji.custom_emoji.uid = "\\{uid}" OR user.name = "users/\\{user}" emoji.unicode = "🙂" OR emoji.custom_emoji.uid = "\\{uid}" AND user.name = "users/\\{user}"

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.

Format: spaces/{space}.

Negative values return an INVALID_ARGUMENT error.

When paginating, all other parameters provided to list space events must match the call that provided the page token. Passing different values to the other parameters might lead to unexpected results.

You must specify at least one event type (event_type) using the has : operator. To filter by multiple event types, use the OR operator. Omit batch event types in your filter. The request automatically returns any related batch events. For example, if you filter by new reactions (google.workspace.chat.reaction.v1.created), the server also returns batch new reactions events (google.workspace.chat.reaction.v1.batchCreated). For a list of supported event types, see the SpaceEvents reference documentation.

Optionally, you can also filter by start time (start_time) and end time (end_time):

• start_time: Exclusive timestamp from which to start listing space events. You can list events that occurred up to 28 days ago. If unspecified, lists space events from the past 28 days.
• end_time: Inclusive timestamp until which space events are listed. If unspecified, lists events up to the time of the request.

To specify a start or end time, use the equals = operator and format in RFC-3339. To filter by both start_time and end_time, use the AND operator.

For example, the following queries are valid:

start_time="2023-08-23T19:20:33+00:00" AND end_time="2023-08-23T19:21:54+00:00" start_time="2023-08-23T19:20:33+00:00" AND (event_types:"google.workspace.chat.space.v1.updated" OR event_types:"google.workspace.chat.message.v1.created")

The following queries are invalid:

start_time="2023-08-23T19:20:33+00:00" OR end_time="2023-08-23T19:21:54+00:00" event_types:"google.workspace.chat.space.v1.updated" AND event_types:"google.workspace.chat.message.v1.created"

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.

If unspecified, at most 100 spaces are returned.

The maximum value is 1000. If you use a value more than 1000, it's automatically changed to 1000.

Negative values return an INVALID_ARGUMENT error.

When paginating, the filter value should match the call that provided the page token. Passing a different value may lead to unexpected results.

You can filter spaces by the space type (space_type).

To filter by space type, you must specify valid enum value, such as SPACE or GROUP_CHAT (the space_type can't be SPACE_TYPE_UNSPECIFIED). To query for multiple space types, use the OR operator.

For example, the following queries are valid:

space_type = "SPACE" spaceType = "GROUP_CHAT" OR spaceType = "DIRECT_MESSAGE"

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires either the chat.admin.spaces.readonly or chat.admin.spaces OAuth 2.0 scope.

This method currently only supports admin access, thus only true is accepted for this field.

If unspecified, at most 100 spaces are returned.

The maximum value is 1000. If you use a value more than 1000, it's automatically changed to 1000.

When paginating, all other parameters provided should match the call that provided the page token. Passing different values to the other parameters might lead to unexpected results.

You can search by using the following parameters:

• create_time
• customer
• display_name
• external_user_allowed
• last_active_time
• space_history_state
• space_type

create_time and last_active_time accept a timestamp in RFC-3339 format and the supported comparison operators are: =, <, >, <=, >=.

customer is required and is used to indicate which customer to fetch spaces from. customers/my_customer is the only supported value.

display_name only accepts the HAS (:) operator. The text to match is first tokenized into tokens and each token is prefix-matched case-insensitively and independently as a substring anywhere in the space's display_name. For example, Fun Eve matches Fun event or The evening was fun, but not notFun event or even.

external_user_allowed accepts either true or false.

space_history_state only accepts values from the historyState field of a space resource.

space_type is required and the only valid value is SPACE.

Across different fields, only AND operators are supported. A valid example is space_type = "SPACE" AND display_name:"Hello" and an invalid example is space_type = "SPACE" OR display_name:"Hello".

Among the same field, space_type doesn't support AND or OR operators. display_name, 'space_history_state', and 'external_user_allowed' only support OR operators. last_active_time and create_time support both AND and OR operators. AND can only be used to represent an interval, such as last_active_time < "2022-01-01T00:00:00+00:00" AND last_active_time > "2023-01-01T00:00:00+00:00".

The following example queries are valid:

``` customer = "customers/my_customer" AND space_type = "SPACE"

customer = "customers/my_customer" AND space_type = "SPACE" AND display_name:"Hello World"

customer = "customers/my_customer" AND space_type = "SPACE" AND (last_active_time < "2020-01-01T00:00:00+00:00" OR last_active_time > "2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND space_type = "SPACE" AND (display_name:"Hello World" OR display_name:"Fun event") AND (last_active_time > "2020-01-01T00:00:00+00:00" AND last_active_time < "2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND space_type = "SPACE" AND (create_time > "2019-01-01T00:00:00+00:00" AND create_time < "2020-01-01T00:00:00+00:00") AND (external_user_allowed = "true") AND (space_history_state = "HISTORY_ON" OR space_history_state = "HISTORY_OFF") ```

Optional. How the list of spaces is ordered.

Supported attributes to order by are:

• membership_count.joined_direct_human_user_count — Denotes the count of human users that have directly joined a space.
• last_active_time — Denotes the time when last eligible item is added to any topic of this space.
• create_time — Denotes the time of the space creation.

Valid ordering operation values are:

• ASC for ascending. Default value.

• DESC for descending.

The supported syntax are:

• membership_count.joined_direct_human_user_count DESC
• membership_count.joined_direct_human_user_count ASC
• last_active_time DESC
• last_active_time ASC
• create_time DESC
• create_time ASC

To create a space, set Space.spaceType to SPACE and set Space.displayName. 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.

To create a group chat, set Space.spaceType to GROUP_CHAT. Don't set Space.displayName.

To create a 1:1 conversation between humans, set Space.spaceType to DIRECT_MESSAGE and set Space.singleUserBotDm to false. Don't set Space.displayName or Space.spaceDetails.

To create an 1:1 conversation between a human and the calling Chat app, set Space.spaceType to DIRECT_MESSAGE and Space.singleUserBotDm to true. Don't set Space.displayName or Space.spaceDetails.

If a DIRECT_MESSAGE space already exists, that space is returned instead of creating a new space.

The set currently allows up to 20 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).

Required. The field paths to update. Separate multiple values with commas or use * to update all field paths.

Currently supported field paths:

• role

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.memberships OAuth 2.0 scope.

Required. The field paths to update. Separate multiple values with commas or use * to update all field paths.

Currently supported field paths:

• text

• attachment

• cards (Requires app authentication.)

• cards_v2 (Requires app authentication.)

• accessory_widgets (Requires app authentication.)

Required. The updated field paths, comma separated if there are multiple.

You can update the following fields for a space:

space_details: Updates the space's description. Supports up to 150 characters.

display_name: Only supports updating the display name for spaces where spaceType field is SPACE. If you receive the error message ALREADY_EXISTS, try a different value. An existing space within the Google Workspace organization might already use this display name.

space_type: Only supports changing a GROUP_CHAT space type to SPACE. Include display_name together with space_type in the update mask and ensure that the specified space has a non-empty display name and the SPACE space type. Including the space_type mask and the SPACE type in the specified space when updating the display name is optional if the existing space already has the SPACE type. Trying to update the space type in other ways results in an invalid argument error. space_type is not supported with useAdminAccess.

space_history_state: Updates space history settings by turning history on or off for the space. Only supported if history settings are enabled for the Google Workspace organization. To update the space history state, you must omit all other field masks in your request. space_history_state is not supported with useAdminAccess.

access_settings.audience: Updates the access setting of who can discover the space, join the space, and preview the messages in named space where spaceType field is SPACE. If the existing space has a target audience, you can remove the audience and restrict space access by omitting a value for this field mask. To update access settings for a space, the authenticating user must be a space manager and omit all other field masks in your request. You can't update this field if the space is in import mode. To learn more, see Make a space discoverable to specific users. access_settings.audience is not supported with useAdminAccess.

permission_settings: Supports changing the permission settings of a space. When updating permission settings, you can only specify permissionSettings field masks; you cannot update other field masks at the same time. permissionSettings is not supported with useAdminAccess. The supported field masks include:

• permission_settings.manageMembersAndGroups
• permission_settings.modifySpaceDetails
• permission_settings.toggleHistory
• permission_settings.useAtMentionAll
• permission_settings.manageApps
• permission_settings.manageWebhooks
• permission_settings.replyMessages

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires the chat.admin.spaces OAuth 2.0 scope.

Some FieldMask values are not supported using admin access. For details, see the description of update_mask.