This page explains how Google Chat apps can receive and respond to events in Google Chat.
A Google Chat event represents an activity or change in Chat, such as a new message in a space. Your Chat app can use events to understand what happened and take action or respond in a meaningful way for your users.
Here are some examples of how you can use events:
- Monitor and respond to new messages in a space, such as checking for key words or phrases.
- Send a welcome message to users as they join the space, to explain the space guidelines or share tips about how to effectively use the Chat app.
- Track and analyze Chat activity. For example, to send a monthly report about new members or the messages that get the most reactions or replies.
- Communicate across messaging platforms. For example, users can send and receive messages from users from a different messaging platform without leaving Chat.
How events work
Whenever something happens in Google Chat, a Google Chat API resource is created, updated, or deleted. Events deliver information about when the activity occurred, and the Chat API resource that was affected.
Chat categorizes events by type. Event types help you filter and request only the type of information you need, and let you handle similar events in the same way.
The following table shows how an activity in Chat affects a related Chat API resource, and the type of event that your Chat app receives:
| Activity | Chat API resource | Event type |
|---|---|---|
A user posts a message in a Chat space |
A Message resource is created. |
New message |
| A user becomes a space manager. | A Membership resource is updated. |
Updated membership |
| A user reacts to a message. | A Reaction resource is created. |
New reaction |
| A user leaves a space. | A Membership resource is deleted. |
Deleted membership |
Receive events from Google Chat
To receive events, your Chat app can do either of the following:
- Subscribe to events using the Google Workspace Events API to receive events as they occur.
- Query for events by calling the Chat API.
The Google Workspace Events API and Chat API support and deliver the same event types. To understand whether you should subscribe to or query for events, review the following table:
| Subscribe to events | Query for events | |
|---|---|---|
| Use cases |
|
|
| API | Google Workspace Events API | Chat API |
| Source of events | Spaces and users | Spaces only |
| Event format | A Google Cloud Pub/Sub message, formatted according to the CloudEvent specification. For details, see Structure of Google Workspace events. |
A Chat API resource
(
spaces.spaceEvent)
|
| Event data | Base64-encoded string with or without resource data. For example payloads, see Event data. | JSON payload that contains resource data. Some event types only include certain resource fields. For example payloads, see the SpaceEvents reference documentation. |
To learn about creating subscriptions using the Google Workspace Events API, see the Google Workspace Events API documentation. To query events using the Chat API, see the following guides:
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.