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.

To learn more about developing Google Chat app, see the Google Chat API overview.

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 or updated 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:

Event type Description Resource data
Subscriptions to spaces  

google.workspace.chat.message.v1.created

A new message is posted.

space.message

google.workspace.chat.message.v1.updated

A message is updated.

space.message

google.workspace.chat.reaction.v1.created

A reaction is created.

space.message.reaction

google.workspace.chat.reaction.v1.deleted

A reaction is deleted.

space.message.reaction

google.workspace.chat.membership.v1.created

A member is created in this space.

space.membership

google.workspace.chat.membership.v1.updated

A member is updated in this space.

space.membership

google.workspace.chat.membership.v1.deleted

A member is removed in this space.

space.membership

google.workspace.chat.space.v1.updated

The space is updated.

space

google.workspace.chat.space.v1.deleted

The space is deleted.

space

Subscriptions to users  

google.workspace.chat.membership.v1.created

The user becomes a member of a space.

space.membership

google.workspace.chat.membership.v1.updated

The user's membership to a space is updated.

space.membership

google.workspace.chat.membership.v1.deleted

The user is removed as a member of a space.

space.membership

Output only event types

Subscribing to google.workspace.APPLICATION.RESOURCE.VERSION.ACTION event types automatically sets up the subscription to also receive batched versions of the event type. For example, if you subscribe to google.workspace.chat.membership.v1.created, you also receive events for google.workspace.chat.membership.v1.batchCreated.

The following table displays which event types are output only for subscriptions to spaces and users:

Event type Description Resource data

google.workspace.chat.message.v1.batchCreated

Multiple messages are posted at the same time.

List of spaces.messages

google.workspace.chat.message.v1.batchUpdated

Multiple messages are updated at the same time.

List of spaces.messages

google.workspace.chat.reaction.v1.batchCreated

Multiple reactions are created at the same time.

List of spaces.messages.reactions

google.workspace.chat.reaction.v1.batchDeleted

Multiple reactions are deleted at the same time.

List of spaces.messages.reactions

google.workspace.chat.membership.v1.batchCreated

  • If target_resource is a space: multiple members are created in the space.
  • If target_resource is a user: the user becomes a member of multiple spaces.

List of spaces.memberships

google.workspace.chat.membership.v1.batchUpdated

  • If target_resource is a space: multiple members are updated in the space.
  • If target_resource is a user: the user's memberships to spaces has multiple updates.

List of spaces.memberships

google.workspace.chat.membership.v1.batchDeleted

  • If target_resource is a space: multiple members are removed in the space.
  • If target_resource is a user: the user is removed as a member from multiple spaces.

List of spaces.memberships

google.workspace.chat.space.v1.batchUpdated

The space has multiple updates.

List of spaces

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",
        }
      }
    ]
}