订阅 Google Chat 活动

本页面介绍了 Chat 应用可以使用 Google Workspace Events API 订阅的 Chat 事件。确定所需的事件类型后，请创建订阅，开始接收来自 Chat 的事件。

除了订阅事件之外，您还可以通过调用 Google Chat API 来查询事件。通过调用 Chat API，您可以定期检索事件，或补上因服务中断而可能错过的订阅事件。如需了解接收和响应 Chat 事件的方式，请参阅 Chat 文档中的处理 Chat 中的事件。

支持的 Chat 事件

通过 Google Workspace 订阅，您可以接收有关 Chat 中以下类型更改的事件：

可监控事件的资源

如需接收事件，您需要指定要监控的 Chat 资源，该资源称为订阅的目标资源。

Google Workspace Events API 支持以下 Chat 目标资源：

目标资源 格式 限制
空格

//chat.googleapis.com/spaces/SPACE

其中，SPACE 是 Chat API space 资源的 资源名称中的 ID。 您可以从聊天室的网址中获取 ID，也可以使用 spaces.list() 方法获取。

 授权订阅的 Chat 用户或 Chat 应用必须通过其 Google Workspace 或 Google 账号成为聊天室的成员。支持：
用户的所有空间

//chat.googleapis.com/spaces/-

 订阅只会接收用户通过其 Google Workspace 或 Google 账号加入的聊天室的事件。仅支持用户身份验证。
用户

//cloudidentity.googleapis.com/users/USER

其中，USER 是 Chat API user 资源的 资源名称中的 ID。如需了解详情，请参阅识别和指定 Google Chat 用户。

订阅仅接收有关授权订阅的用户事件。用户无法代表其他用户授权订阅。仅支持用户身份验证。
客户

//admin.googleapis.com/customers/CUSTOMER

其中，CUSTOMER 是客户 ID。您还可以为 Chat 应用的客户网域使用 my_customer 别名。

订阅会接收客户网域管理的所有聊天室和用户的事件。仅支持需要管理员批准的应用身份验证。

用于创建订阅的事件类型

创建订阅时，请使用 eventTypes[] 字段指定您要接收的事件类型。事件类型根据 CloudEvents 规范进行格式化，例如 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION。

例如，如需接收有关用户加入 Chat 聊天室的事件，请将聊天室指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需接收有关给定用户加入任何聊天室的事件，请将该用户指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需详细了解事件的工作原理，请参阅 Google Workspace 事件的结构。

下表显示了订阅聊天室和订阅用户支持哪些事件类型。如需了解触发事件的例外情况，请参阅限制。

事件类型 格式 资源数据
订阅聊天室  
消息已发布。

google.workspace.chat.message.v1.created

space.message
消息已更新。

google.workspace.chat.message.v1.updated

space.message
消息已删除。

google.workspace.chat.message.v1.deleted

space.message
创建了回应。

google.workspace.chat.reaction.v1.created

space.message.reaction
回应被删除。

google.workspace.chat.reaction.v1.deleted

space.message.reaction
有成员被添加到聊天室。

google.workspace.chat.membership.v1.created

space.membership
聊天室中的成员已更新。

google.workspace.chat.membership.v1.updated

space.membership
有成员从聊天室中被移除。

google.workspace.chat.membership.v1.deleted

space.membership
聊天室已更新。

google.workspace.chat.space.v1.updated

space
聊天室已被删除。

google.workspace.chat.space.v1.deleted

space
用户订阅  
用户成为聊天室成员。

并非所有新成员都会触发事件。如需了解详情，请参阅限制

google.workspace.chat.membership.v1.created

space.membership
用户的聊天室成员资格已更新。

google.workspace.chat.membership.v1.updated

space.membership
用户被移除，不再是聊天室的直接成员。

google.workspace.chat.membership.v1.deleted

space.membership
用户的聊天室已读状态已更新。

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
用户的会话已读状态已更新。

google.workspace.chat.threadReadState.v1.updated

threadReadState
客户订阅  
Google Workspace 组织内的任何聊天室、消息、回应、成员资格或用户已读状态发生事件。

支持为聊天室和用户订阅列出的所有事件类型。

取决于事件类型（例如 space、space.message、space.membership 或 spaceReadState）。

批量事件类型（仅限输出）

除了接收您订阅的事件类型之外，您的 Chat 应用可能还会接收批量事件。批处理事件是指代表短时间内发生的许多同类型事件的事件。批量事件的载荷包含所有已更改资源的列表。

例如，如果用户同时向聊天室添加 20 位用户，您的 Chat 应用可能会收到批量事件 (google.workspace.chat.membership.v1.batchCreated)。事件载荷包含用户将成员添加到聊天室时创建的所有新 Membership 资源的列表。

您会收到您订阅的任何事件类型的批处理事件，因此您在创建订阅时无需指定批处理事件。例如，如果您订阅了新回应 (google.workspace.chat.reaction.v1.created)，则您的 Chat 应用会自动配置为接收批量回应事件 (google.workspace.chat.reaction.v1.batchCreated)。

下表显示了订阅可能发生的批量事件：

批处理事件类型 格式
发布了多条消息。

google.workspace.chat.message.v1.batchCreated
多条消息已更新。

google.workspace.chat.message.v1.batchUpdated
多条消息已删除。

google.workspace.chat.message.v1.batchDeleted
创建了多个回应。

google.workspace.chat.reaction.v1.batchCreated
多条回应已删除。

google.workspace.chat.reaction.v1.batchDeleted
多个成员已添加到订阅的聊天室，或者订阅的用户已添加到多个聊天室。

google.workspace.chat.membership.v1.batchCreated
订阅的聊天室或订阅的用户中的多个成员资格已更新。

google.workspace.chat.membership.v1.batchUpdated
多位成员已从订阅的聊天室中移除，或订阅的用户已从多个聊天室中移除。

google.workspace.chat.membership.v1.batchDeleted
该聊天室有多项更新。

google.workspace.chat.space.v1.batchUpdated
系统会为订阅用户更新多个聊天室的已读状态。

google.workspace.chat.spaceReadState.v1.batchUpdated
为订阅用户更新了多个会话的已读状态。

google.workspace.chat.threadReadState.v1.batchUpdated

事件数据

本部分介绍了 Chat 中事件的事件数据和示例载荷。

当您的 Google Workspace 订阅收到来自 Chat 的事件时，data 字段会包含该事件的载荷。此载荷包含有关已更改的 Google Workspace 资源的信息。例如，如果您订阅了聊天室中的成员资格事件，则这些事件的载荷会包含有关已更改的 spaces.membership 资源的信息。

事件载荷中的资源数据

创建订阅时，您可以指定载荷是包含资源的详细信息，还是仅包含资源的名称。例如，如果您想接收有关 Chat 聊天室中成员的事件，请指定要在事件载荷中接收成员资格资源的哪些字段。

下表提供了订阅 Chat 聊天室 spaces/AAAABBBBBB 的 JSON 载荷示例。对于订阅收到的每个事件，载荷会显示在事件的 data 字段中：

示例 事件类型 JSON 载荷

用户在聊天室中发布一条消息，内容为“Hello world”。

google.workspace.chat.message.v1.created

包含资源数据：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

排除资源数据：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
用户成为聊天室管理员。

google.workspace.chat.membership.v1.updated

包含资源数据：

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

排除资源数据：

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
用户将聊天室说明更新为“Cymbal Labs 销售团队”。 google.workspace.chat.space.v1.updated

包含资源数据：

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

排除资源数据：

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
同时向聊天室添加了两个 Chat 用户。 google.workspace.chat.membership.v1.batchCreated

包含资源数据：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

排除资源数据：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
用户使用 😊 表情符号回应消息。 google.workspace.chat.reaction.v1.created

包含资源数据：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

排除资源数据：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
用户使用 😊 表情符号和 😸 表情符号回应消息。 google.workspace.chat.reaction.v1.batchCreated

包含资源数据：

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

排除资源数据：

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
用户访问未读聊天室，这会更新其聊天室已读状态。 google.workspace.chat.spaceReadState.v1.updated

包含资源数据：

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

排除资源数据：

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
用户阅读了消息串中的某条消息，这会更新其消息串已读状态。 google.workspace.chat.threadReadState.v1.updated

包含资源数据：

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

排除资源数据：

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
用户在 Chat 中变为可用状态。 google.workspace.chat.availability.v1.updated

包含资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}

排除资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
用户在 Chat 中处于闲置状态。 google.workspace.chat.availability.v1.updated

包含资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}

排除资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
用户在 Chat 中将状态设置为Away。 google.workspace.chat.availability.v1.updated

包含资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}

排除资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
用户在 Chat 中将状态设置为Do not disturb。 google.workspace.chat.availability.v1.updated

包含资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}

排除资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
用户在 Chat 中设置自定义状态。 google.workspace.chat.availability.v1.updated

包含资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}

排除资源数据：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}

限制和投放行为

一般限制

  • 如需接收成员资格事件，用户或 Chat 应用必须是聊天室的直接成员。如果用户是通过 Google 群组间接添加到聊天室、在聊天室中更新或从聊天室中移除，则订阅不会收到这些成员资格事件。如需了解 Google 群组成员资格的运作方式，请参阅向聊天室添加 Google 群组。

用户订阅

  • 对于用户订阅，只有在发布第一条消息后，才会触发有关私信或未命名群聊 (google.workspace.chat.membership.v1.created) 中新成员的事件。

客户订阅

对于客户订阅，存在以下限制：

  • Google Workspace 组织必须至少有一个企业版 SKU 许可。
  • Chat 应用只能为给定的 Google Workspace 组织创建一个客户订阅。一个 Google Workspace 组织总共最多可以有 5 个客户订阅（由不同的 Chat 应用创建）。

对于客户订阅，事件传送遵循以下一般规则：

  • 聊天室事件：仅当事件发生在由您的 Google Workspace 组织管理的聊天室中时，才会传送。
  • 用户事件：仅在事件发生在属于您 Google Workspace 组织的用户时才会传送。

这些规则的唯一例外是成员资格事件。您的订阅可以接收来自贵组织管理的聊天室和外部组织管理的聊天室的成员资格事件，但这些事件的传递方式取决于哪个组织管理该聊天室：

由您的 Google Workspace 组织管理的聊天室

如果 Google Workspace 组织管理的聊天室中发生成员资格变更，则会以聊天室事件的形式传递。

空间事件的资源名称采用以下格式：

spaces/{spaceId}/spaceEvents/{spaceEventId}

由外部组织管理的聊天室

如果由您的 Google Workspace 组织管理的用户在由外部组织管理的聊天室（例如，外部命名聊天室或由外部用户创建的私信）中的成员资格发生变化，您的订阅会将此事件作为用户事件接收。

用户事件的资源名称采用以下格式：

users/{userId}/userEvents/{userEventId}