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 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.
Resources that you can monitor for events
To receive events, you specify a Chat resource to monitor, which is called the target resource of the subscription.
The Google Workspace Events API supports the following target resources for Chat:
| Target resource | Format | Limitations |
|---|---|---|
| Space |
where SPACE is the ID in the
resource name of the Chat API |
The Chat user that authorizes the subscription must be a member of the space through their Google Workspace or Google Account. |
| All spaces for a user |
|
The subscription only receives events for the spaces where the user is a member through their Google Workspace or Google Account. |
| User |
where USER is the ID in the
resource name of the Chat API |
The subscription only receives events about the user that authorized the subscription. A user can't authorize a subscription on behalf of other users. |
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. - 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