This page describes the Google Chat events that a Google Chat app can subscribe to using the Google Workspace Events API. After you decide which types of events you need, create a subscription to start receiving events from Google Chat.
In addition to subscribing to events, you can also query for events by calling the Chat API. Calling the Chat API lets you retrieve events on a periodic basis, or catch up on events you might have missed from a subscription due to an outage. To learn about the ways you can receive and respond to Chat events, see Work with events from Google Chat in the Chat documentation.
Supported Chat target resources
The Google Workspace Events API supports subscriptions to:
- Spaces, represented as
space
resources - Users, represented as Cloud Identity API
user
resources
Supported Chat events
Google Workspace subscriptions let you receive events about the following types of changes in Chat:
- New, updated, or deleted messages in the space.
- New or removed reactions to a message.
- New, updated, or removed members in the space.
- Changes to the space that you're subscribed to, such as an updated space name or description.
Event types for creating subscriptions
When you create a subscription, you use the
eventTypes[]
field to specify which types of events you want to receive. Event types are
formatted according to the CloudEvents specification, such as
google.workspace.APPLICATION.RESOURCE.VERSION.ACTION
.
For example, to receive events about users joining a Chat
space, you specify the space as the target resource, and the event type as
google.workspace.chat.membership.v1.created
. To receive events about a given
user joining any space, you specify the user as the target resource, and the
event type as google.workspace.chat.membership.v1.created
. To learn more about
how events work, see Structure of Google Workspace
events.
The following table displays which event types are supported for subscriptions to spaces and subscriptions to users. To learn about exceptions about what triggers an event, see Limitations.
Event type | Format | Resource data | ||
---|---|---|---|---|
Subscriptions to spaces | ||||
A message is posted. |
|
|
||
A message is updated. |
|
|
||
A message is deleted. |
|
|
||
A reaction is created. |
|
|
||
A reaction is deleted. |
|
|
||
A member is added to the space. |
|
|
||
A member is updated in the space. |
|
|
||
A member is removed from the space. |
|
|
||
The space is updated. |
|
|
||
The space is deleted. |
|
|
||
Subscriptions to users | ||||
The user becomes a member of a space.
Not all new members trigger events. For details, see Limitations |
|
|
||
The user's membership to a space is updated. |
|
|
||
The user is removed as a direct member of a space. |
|
|
Batch event types (output only)
In addition to receiving the event types that you subscribe to, your Chat app might also receive batch events. A batch event is an event that represents many events of the same type that occur in a short period of time. The payload of a batch event contains a list of all the changed resources.
For example, if a user adds 20 users to a space at the same time, your
Chat app might receive a batch event
(google.workspace.chat.membership.v1.batchCreated
). The event payload contains
a list of all of the new Membership
resources that were created when the user
added the members to the space.
You receive a batch event for any event type that you subscribe to, so
you don't need to specify batch events when you create a subscription. For
example, if you subscribe to new reactions
(google.workspace.chat.reaction.v1.created
), your
Chat app is automatically configured to receive batch
reaction events (google.workspace.chat.reaction.v1.batchCreated
).
The following table displays the possible batch events for a subscription:
Batch event type | Format |
---|---|
Multiple messages are posted. |
|
Multiple messages are updated. |
|
Multiple messages are deleted. |
|
Multiple reactions are created. |
|
Multiple reactions are deleted. |
|
Multiple members are added to the subscribed space, or the subscribed user has been added to multiple spaces. |
|
Multiple memberships are updated in the subscribed space, or for the subscribed user. |
|
Multiple members are removed from the subscribed space, or the subscribed user has been removed from multiple spaces. |
|
The space has multiple updates. |
|
Event data
This section describes event data and example payloads for events in Chat.
When your Google Workspace subscription receives an event from
Chat, the
data
field contains the payload for the event. This payload has information about the
Google Workspace resource that changed. For example, if you've subscribed to
membership events in a space, the payload for these events contains information
about the
spaces.membership
resource that changed.
Resource data in the event payload
When you create a subscription, you can specify whether you want the payload to include details about the resource, or just the name of the resource. For example, if you want to receive events about members in a Chat space, you can specify which fields of a membership resource you want to receive in the event payload.
The following table provides examples of JSON payloads for a subscription to
the Chat space spaces/AAAABBBBBB
. For each event that the
subscription receives, the payload appears in the data
field of the event:
Example | Event type | JSON payload |
---|---|---|
A user posts a message in the space that says "Hello world." |
|
Includes resource data
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD", "sender": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "2023-09-07T21:37:36.260127Z", "text": "Hello world", "thread": { "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE" }, "space": { "name": "spaces/AAAABBBBBB" }, "argumentText": "Hello world" } } Excludes resource data
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD" } } |
A user becomes a space manager. |
|
Includes resource data
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MANAGER" } } Excludes resource data
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } } |
A user updates the description of the space to "Sales team for Cymbal Labs." | google.workspace.chat.space.v1.updated |
Includes resource data
{ "space": { "name": "spaces/AAAABBBBBB", "displayName": "Cymbal Sales", "spaceThreadingState": "THREADED_MESSAGES", "spaceType": "SPACE", "spaceDetails": { "description": "Sales team for Cymbal Labs." }, "spaceHistoryState": "HISTORY_ON" } } Excludes resource data
{ "space": { "name": "spaces/AAAABBBBBB" } } |
Two Chat users were added to the space at the same time. | google.workspace.chat.membership.v1.batchCreated |
Includes resource data
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/987654321234567890", "state": "JOINED", "member": { "name": "users/987654321234567890", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } } ] } Excludes resource data
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/98765432123456789019" } } ] } |
A user reacts to a message with the 😊 emoji. | google.workspace.chat.reaction.v1.created |
Includes resource data
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } } Omits resource data
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" } } |
Users react to a message with the 😊 emoji and 😸 emoji. | google.workspace.chat.reaction.v1.batchCreated |
Includes resource data
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } }, { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", "user": { "name": "users/98765431234564321", "type": "HUMAN" }, "emoji": { "unicode": "😸" } } } ] } Omits resource data
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" }, "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", } } ] } |
Limitations
-
For subscriptions to users, events about new members in direct messages or unnamed group chats (
google.workspace.chat.membership.v1.created
), only trigger after the first message is posted. - Changes to space history don't trigger updated space events (Event type:
google.workspace.chat.spaces.v1.updated
). - To receive membership events, the user must be a direct member of the space. If a user was added, updated, or removed indirectly to a space through a Google Group, the subscription doesn't receive those membership events. To understand how Google Group memberships work, see Add a Google Group to a space.
Related topics
- Structure of Google Workspace events
- Choose OAuth scopes
- Create a subscription to receive Chat events