Subscribe to Google Chat events

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

//chat.googleapis.com/spaces/SPACE

where SPACE is the ID in the resource name of the Chat API space resource. You can obtain the ID from the space's URL or using the spaces.list() method.

 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

//chat.googleapis.com/spaces/-

 The subscription only receives events for the spaces where the user is a member through their Google Workspace or Google Account.
User

//cloudidentity.googleapis.com/users/USER

where USER is the ID in the resource name of the Chat API user resource. For details, see Identify and specify Google Chat users.

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.

google.workspace.chat.message.v1.created

space.message
A message is updated.

google.workspace.chat.message.v1.updated

space.message
A message is deleted.

google.workspace.chat.message.v1.deleted

space.message
A reaction is created.

google.workspace.chat.reaction.v1.created

space.message.reaction
A reaction is deleted.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
A member is added to the space.

google.workspace.chat.membership.v1.created

space.membership
A member is updated in the space.

google.workspace.chat.membership.v1.updated

space.membership
A member is removed from the space.

google.workspace.chat.membership.v1.deleted

space.membership
The space is updated.

google.workspace.chat.space.v1.updated

space
The space is deleted.

google.workspace.chat.space.v1.deleted

space
Subscriptions to users  
The user becomes a member of a space.

Not all new members trigger events. For details, see Limitations

google.workspace.chat.membership.v1.created

space.membership
The user's membership to a space is updated.

google.workspace.chat.membership.v1.updated

space.membership
The user is removed as a direct member of a space.

google.workspace.chat.membership.v1.deleted

space.membership

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.

google.workspace.chat.message.v1.batchCreated
Multiple messages are updated.

google.workspace.chat.message.v1.batchUpdated
Multiple messages are deleted.

google.workspace.chat.message.v1.batchDeleted
Multiple reactions are created.

google.workspace.chat.reaction.v1.batchCreated
Multiple reactions are deleted.

google.workspace.chat.reaction.v1.batchDeleted
Multiple members are added to the subscribed space, or the subscribed user has been added to multiple spaces.

google.workspace.chat.membership.v1.batchCreated
Multiple memberships are updated in the subscribed space, or for the subscribed user.

google.workspace.chat.membership.v1.batchUpdated
Multiple members are removed from the subscribed space, or the subscribed user has been removed from multiple spaces.

google.workspace.chat.membership.v1.batchDeleted
The space has multiple updates.

google.workspace.chat.space.v1.batchUpdated

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."

google.workspace.chat.message.v1.created

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.

google.workspace.chat.membership.v1.updated

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.