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.

Subscription events from Google Chat are structured according to the CloudEvents specification. To learn more, see the Structure of Google Workspace events.

Supported Chat target resources

The Google Workspace Events API supports subscriptions to Chat spaces, represented as space 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.

When you create a subscription to a Google Chat space, 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 new messages in a Chat space, you specify the event type as google.workspace.chat.message.v1.created.

The following table displays the supported event types, a description, and the changed Chat resource that's represented in the event data:

Event type Description Chat resource

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.

spaces.messages.reaction

google.workspace.chat.reaction.v1.deleted

A reaction is deleted.

spaces.messages.reaction

google.workspace.chat.reaction.v1.batchChanged

Multiple reactions have changed.

spaces.messages.reaction

google.workspace.chat.membership.v1.created

A member is created.

space.membership

google.workspace.chat.membership.v1.updated

A member is updated.

space.membership

google.workspace.chat.membership.v1.deleted

A member is removed.

space.membership

google.workspace.chat.membership.v1.batchChanged

Multiple memberships have changed.

space.membership

google.workspace.chat.space.v1.updated

The space is updated.

space

google.workspace.chat.space.v1.deleted

The space is deleted.

space

Event data

This section describes event data and example payloads for events in Chat spaces.

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.batchChanged
Includes resource data
{
    "createdMemberships":
    [
        {
            "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"
            }
        }
    ],
    "updatedMemberships":
    [],
    "deletedMemberships":
    []
}
Excludes resource data
{
    "createdMemberships":
    [
        {
            "membership":
            {
                "name": "spaces/AAAABBBBBB/members/1234567890987654321"
            }
        },
        {
            "membership":
            {
                "name": "spaces/AAAABBBBBB/members/98765432123456789019"
            }
        }
    ],
    "updatedMemberships":
    [],
    "deletedMemberships":
    []
}
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.batchChanged
Includes resource data
{
    "createdReactions":
    [
        {
            "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": "😸"
                }
            }
        }
    ],
    "deletedReactions":
    []
}
Omits resource data
{
    "createdReactions":
    [
        {
            "reaction":
            {
                "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
            },
            "reaction":
            {
                "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
            }
        }
    ],
    "deletedReactions":
    []
}