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 on 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. Chat uses events to deliver information to your Chat app about the type of activity that occurred, and the Chat API resource that was affected.
Chat categorizes events by type. Event types help you filter and receive only the type of information you need, and let you handle similar activities 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 recent events by calling the Chat API.
The following table explains the difference and reasons for querying or subscribing to events:
Subscribe to events | Query for events | |
---|---|---|
Use cases |
|
|
API | Google Workspace Events API | Chat API |
Source of events | Spaces and users | Spaces only |
Supported events |
For a list of supported event types, see Event types for creating subscriptions in the Google Workspace Events API documentation. |
For a list of supported event types, see the spaceEvents resource in the Chat API
reference documentation.
|
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 reference documentation. |
Example: Query or subscribe to events about memberships in a space
In this example, a Chat app wants to receive information about changes to members of a Chat space. In the space, the following membership activity occurs:
- A user joins the space, which creates a
Membership
resource and triggers a new member event. - A user becomes a space manager, which updates the
Membership
resource for the user and triggers an updated member event. - A user leaves the space, which deletes the
Membership
resource for the user and triggers a member deleted event.
Subscribe to membership events
To receive events in real time, the
Chat app calls the Google Workspace Events API
subscriptions.create()
method to subscribe to the space for all types of membership events. After
creating the subscription, the Chat app can start to
receive membership events.
In figure 2, the Chat app has an active subscription to the space, so the app receives an event whenever a membership in the space changes. The Chat app can then process or respond in real time to any of the activities, such as posting a private welcome message to the member who joined the space.
To learn about creating subscriptions using the Google Workspace Events API, see the Google Workspace Events API documentation.
Query for recent membership events
Instead of receiving the membership events as they occur, a Chat app can call the Chat API to list recent space events that are related to membership activity.
In figure 3, a Chat app calls the Chat API
spaces.spaceEvents.list()
method after all the membership activities have occurred, and filters the query
for new, updated, and deleted membership events. The Chat API returns
a list of spaceEvent
resources that represent each of the membership changes.
The Chat app can then process or respond based on the
recent activity, such as posting a weekly message with a summary of the
space's membership activity in the past 7 days.
To query for events using the Chat API, see List events from a Google Chat space.
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
- Google Workspace Events API overview
- Create a subscription
- Get details about a Google Chat space event
- List events from a Google Chat space
- For examples of how to use events, see the tutorial Answer questions based on Chat conversations with a Gemini AI Chat app or the inclusivity help feature of the issue management Chat app in the codelab Build apps for Google Chat with Gemini.