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

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.

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:

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:

{
    "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"
    }
}
      

{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
      

{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321",
        "state": "JOINED",
        "member":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
      

{
    "space":
    {
        "name": "spaces/AAAABBBBBB",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

{
    "space":
    {
        "name": "spaces/AAAABBBBBB"
    }
}
      

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

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
      

{
    "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/1111111111111111.222222222222222"
    }
}
      

{
    "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": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}
      

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

Related topics

• Structure of Google Workspace events
• Choose OAuth scopes
• Create a subscription to receive Chat events