Google Chat 数据 API：端点与字段

Google Chat 是 Google LLC 为 Google Workspace 推出的团队通讯应用，最早以 Hangouts Chat 之名上线，2020 年改名为 Google Chat，之后也取代了个人 Google 账号使用的经典版 Hangouts；它的核心是一个汇总全部聊天室和私信、并标出各自未读数的首页收件箱。用户在命名聊天室里按话题讨论，发起可带附件、格式文本和引用回复的新话题并在话题内回复，进行一对一或群组私信，也能随时加入临时语音通话（huddles）；成员管理面板列出每个聊天室有哪些成员、各自是什么角色，头像上的在线圆点和状态行显示同事是否在线、是否开了免打扰、有没有设置带表情的自定义状态，搜索栏既能在所有聊天室里、也能只在某个命名聊天室里找回历史消息，发起聊天、创建私信和 @提及时的联想则直接取自公司通讯录。它是一款职场协作工具，Workspace 组织用它配合 Gmail、云端硬盘、日历和 Meet 完成日常团队协同，在 Android 上同样的对话也会出现在 Gmail 应用里；Android 应用已在美国、印度、巴西等市场上架，主要竞品包括 Slack、Microsoft Teams、Zoom Workplace 内置的聊天、Discord，以及可自行部署、基于 Matrix 的 Element。

聊天室与私信是最基础的对象：每个都对应一个 groupId 与 groupName，命名聊天室另带 roomAvatarUrl，私信另带 primaryDmPartnerUserId；收件箱数据按 worldSectionType 分区翻页列出它们，附带每个聊天室的 unreadCount、sectionWatermark、翻页用的 paginationToken 与 hasMoreItems 标记，并一并带回当前可见的 includedMembers。每个聊天室都有一份成员名册，每位成员带有 memberId、nullableEmail、displayName、givenName、familyName、avatarUrl 与 membershipRole，另有 placeholderUser 标记。在此之上是实时可用性：按一批 memberIds 查询，以 userStatusMap 返回 presenceState，含 dndState 与 dndExpiryTimeMicros 的 dndStatus，以及由 statusText、statusEmoji 和 clearAfterMicros 组成的 customStatus，是否对外可见由 presenceShared 标记控制。

对话本身构成消息层：一个话题是一个 topicId，每条消息是一个 messageId，带有 messageText、格式 annotations、attachments、可选的 quotedMessage、createTimeMicros、creatorMemberId 以及发出它的 originAppId。对这些历史消息的全文搜索可用 fromSelfForSearch 或 namedRoomForSearch 收窄范围，返回 matchedMessages，附来源 groupName、文本 snippet 和 resultCount。Workspace 人员目录把输入的姓名解析为 personId、emailAddress、givenName、familyName 与 avatarUrl；而 memberId 把名册条目、在线状态查询和该成员所发每条消息上的 creatorMemberId 串联在一起。

这套结构直接对应具体的内部工具：IT 与安全团队导出聊天室名册（groupId、groupName、memberId、nullableEmail、membershipRole）做访问权限审查；值班与事件响应系统仅在 presenceState 为 ACTIVE 且 dndStatus 不是 DND 时才呼叫响应者，并把 customStatus 文本当作离开原因；知识管理团队用 messageId、topicId、groupName 和 snippet 灌入内部搜索索引，并把每条命中链接回所在聊天室；工单伴生工具则在打开 Chat 私信前，先把输入的姓名解析为 personId 与 emailAddress。openData Studio 把这些 Google Chat 聊天室、名册、在线状态、话题和目录查询变成可直接调用的开放数据。

应用截图

API 端点一览

以下端点与请求/响应示例均依据应用界面推导重构，为示意说明，并非实际抓包。

分页获取首页聊天室与私聊列表

POST /v1/inbox/page opendata

返回已登录用户 Chat 首页（聊天室与私聊）的一页数据，含 worldSections、worldItems、includedMembers 与 paginationToken，供收件箱首页使用。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（Workspace 聊天权限范围包）。请求为 protobuf 编码的 POST。

pageSize
worldSection
worldFilter
worldTopicFilter
paginationToken
contentSortOrder
foregroundWorldSyncSessionId
shouldRefresh
requestedAllGroups
worldSections
hasMoreItems
sectionWatermark
worldSectionType
includedMembers
memberId
nullableEmail
displayName
givenName
familyName
avatarUrl
worldItems
groupId
groupName
roomAvatarUrl
primaryDmPartnerUserId
worldEntities
unreadCount

POST /v1/inbox/page HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "pageSize": 50,
  "worldSection": {
    "worldFilter": "INBOX",
    "worldTopicFilter": "ALL",
    "paginationToken": ""
  },
  "contentSortOrder": "LAST_ACTIVITY_DESC",
  "foregroundWorldSyncSessionId": "ws-7f3a1c2e",
  "shouldRefresh": true
}

{
  "requestedAllGroups": false,
  "worldSections": [{
    "paginationToken": "CgQItoED",
    "sort": "LAST_ACTIVITY_DESC",
    "worldFilter": "INBOX",
    "worldTopicFilter": "ALL",
    "sectionWatermark": "1758902400000000",
    "hasMoreItems": true,
    "worldSectionType": "INBOX"
  }],
  "includedMembers": [{
    "memberId": "user/human/123456789012345678901",
    "nullableEmail": "[email protected]",
    "displayName": "Alex Rivera",
    "givenName": "Alex",
    "familyName": "Rivera",
    "avatarUrl": "https://lh3.googleusercontent.com/a-/AOh14Example"
  }],
  "worldItems": [{
    "groupId": "space/AAAAexample01",
    "groupName": "Platform standup",
    "roomAvatarUrl": "https://lh3.googleusercontent.com/d/space-avatar",
    "primaryDmPartnerUserId": null
  }],
  "worldEntities": [{
    "groupId": "space/AAAAexample01",
    "unreadCount": 3
  }]
}

列出聊天室或群聊成员

POST /v1/spaces/members osint

返回聊天室或群聊的成员名册（memberId、nullableEmail、displayName、avatarUrl、membershipRole），供成员管理与成员面板使用。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（Workspace 聊天权限范围包）。请求为 protobuf 编码的 POST。

groupId
paginationToken
pageSize
members
id
memberId
nullableEmail
displayName
givenName
familyName
avatarUrl
membershipRole
emailAddress
placeholderUser
unknown
serverSyncNeeded
hasMoreItems

POST /v1/spaces/members HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "groupId": "space/AAAAexample01",
  "paginationToken": "",
  "pageSize": 100
}

{
  "members": [{
    "id": "user/human/123456789012345678901",
    "memberId": "user/human/123456789012345678901",
    "nullableEmail": "[email protected]",
    "displayName": "Alex Rivera",
    "givenName": "Alex",
    "familyName": "Rivera",
    "avatarUrl": "https://lh3.googleusercontent.com/a-/AOh14Example",
    "membershipRole": "ROLE_MEMBER",
    "user": {
      "emailAddress": "[email protected]"
    },
    "placeholderUser": false,
    "unknown": false,
    "serverSyncNeeded": false
  }],
  "paginationToken": "EgwIAhABGAEgASgB",
  "hasMoreItems": false
}

读取用户在线状态、免打扰与自定义状态

POST /v1/presence/lookup osint

返回一个或多个 memberIds 的 presenceState、dndStatus、customStatus 与 presenceShared，为头像上的在线状态圆点与私聊状态行提供数据。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（Workspace 聊天权限范围包）。请求为 protobuf 编码的 POST。

memberIds
userStatusMap
presenceState
dndStatus
dndState
dndExpiryTimeMicros
customStatus
statusText
statusEmoji
clearAfterMicros
presenceShared

POST /v1/presence/lookup HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "memberIds": [
    "user/human/123456789012345678901",
    "user/human/987654321098765432109"
  ]
}

{
  "userStatusMap": {
    "user/human/123456789012345678901": {
      "presenceState": "ACTIVE",
      "dndStatus": {
        "dndState": "AVAILABLE",
        "dndExpiryTimeMicros": 0
      },
      "customStatus": {
        "statusText": "In a huddle",
        "statusEmoji": ":headphones:",
        "clearAfterMicros": 1758906000000000
      },
      "presenceShared": true
    }
  }
}

在聊天室创建新话题（线程）

POST /v1/threads/create opendata

在聊天室发布新话题（messageText、annotations、attachments、messageId），并返回消息流使用的 topicId。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（Workspace 聊天权限范围包）。请求为 protobuf 编码的 POST。

groupId
messageText
annotations
quotedMessage
messageId
acceptFormatAnnotations
attachments
messageCreationTimeInMicros
originAppId
unsentMessageId
topicId
createTimeMicros
creatorMemberId

POST /v1/threads/create HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "groupId": "space/AAAAexample01",
  "messageText": "Ship notes for Friday's release",
  "annotations": [],
  "quotedMessage": null,
  "messageId": "spaces/AAAAexample01/messages/MSG-7f3a",
  "acceptFormatAnnotations": true,
  "attachments": [],
  "messageCreationTimeInMicros": 1758902400000000,
  "originAppId": null,
  "unsentMessageId": null
}

{
  "topicId": "spaces/AAAAexample01/threads/THD-9c2b",
  "messageId": "spaces/AAAAexample01/messages/MSG-7f3a",
  "groupId": "space/AAAAexample01",
  "messageText": "Ship notes for Friday's release",
  "createTimeMicros": 1758902400123000,
  "creatorMemberId": "user/human/123456789012345678901"
}

跨聊天室搜索消息

POST /v1/messages/search opendata

在 Chat 历史记录上运行 Hub Search（query、filter、sessionId），返回含 messageId、topicId、groupName 与文本摘要的 matchedMessages。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（Workspace 聊天权限范围包加搜索查询范围）。请求为 protobuf 编码的 POST。

query
queryId
filter
groupId
fromSelfForSearch
namedRoomForSearch
size
isPagination
sessionId
searchSurface
matchedMessages
messageId
topicId
groupName
messageText
createTimeMicros
creatorMemberId
snippet
paginationToken
resultCount

POST /v1/messages/search HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "query": "invoice Q3",
  "queryId": "q-8e1c2a",
  "filter": {
    "groupId": null,
    "fromSelfForSearch": false,
    "namedRoomForSearch": true
  },
  "size": 25,
  "isPagination": false,
  "sessionId": "search-sess-44ab",
  "searchSurface": "HUB_SEARCH"
}

{
  "matchedMessages": [{
    "messageId": "spaces/AAAAexample01/messages/MSG-11aa",
    "topicId": "spaces/AAAAexample01/threads/THD-9c2b",
    "groupId": "space/AAAAexample01",
    "groupName": "Finance",
    "messageText": "Q3 invoice is in the shared Drive folder",
    "createTimeMicros": 1758816000000000,
    "creatorMemberId": "user/human/123456789012345678901",
    "snippet": "Q3 invoice is in the shared Drive folder"
  }],
  "paginationToken": "CgoIARABGAEgAQ",
  "resultCount": 18
}

目录中的人员自动补全

POST /v1/directory/autocomplete osint

为发起聊天/创建私聊/@提及提供 Workspace 目录输入联想，返回 personId、displayName、givenName、familyName、emailAddress 与 avatarUrl。

认证方式：已登录 Google 账号的 OAuth2 Bearer 访问令牌（只读人员目录范围）。

query
maxResults
client
results
id
personId
displayName
givenName
familyName
emailAddress
avatarUrl

POST /v1/directory/autocomplete HTTP/1.1
Authorization: Bearer <oauth2-access-token>
Content-Type: application/x-protobuf

{
  "query": "alex ri",
  "maxResults": 8,
  "client": "GOOGLE_CHAT_ANDROID"
}

{
  "results": [{
    "id": "people/c123456789012345678901",
    "personId": "people/c123456789012345678901",
    "displayName": "Alex Rivera",
    "givenName": "Alex",
    "familyName": "Rivera",
    "emailAddress": "[email protected]",
    "avatarUrl": "https://lh3.googleusercontent.com/a-/AOh14Example"
  }]
}

数据类别

聊天室
私聊消息
成员关系
在线状态
消息
人员目录

数据使用场景与案例

Workspace 名册导出
先拉取 /v1/inbox/page，再逐聊天室调用 /v1/spaces/members，构建 groupId、groupName、memberId、nullableEmail、membershipRole 与 avatarUrl 的内部映射，用于访问权限审查。
基于在线状态的路由
对值班 memberIds 调用 /v1/presence/lookup，仅当 presenceState 为 ACTIVE 且 dndStatus 非 DND 时才路由呼叫，并把 customStatus 文本作为离开原因。
Chat 话题知识索引
用 /v1/messages/search（query、sessionId、matchedMessages）把 messageId、topicId、groupName 与 snippet 灌入内部搜索索引，再通过 groupId 打开来源聊天室。
伴生应用中的目录联想
代理 /v1/directory/autocomplete 调用，让工单工具在打开 Chat 私聊前，把 query 解析为 personId、emailAddress、givenName、familyName 与 avatarUrl。

常见问题

Google Chat 如何认证私有数据调用？

客户端为已登录 Google 账号签发 OAuth2 访问令牌，附带 Workspace 聊天权限范围包（另有通讯录、云端硬盘与日历权限）。调用是 protobuf 编码的 POST，用 Authorization: Bearer 请求头认证。

哪些端点暴露聊天室、成员与在线状态？

/v1/inbox/page 分页返回首页的聊天室与私聊列表。/v1/spaces/members 返回聊天室名册（memberId、nullableEmail、displayName、membershipRole）。/v1/presence/lookup 返回 presenceState、dndStatus、customStatus 与 presenceShared。

应用内的人员搜索如何工作？

发起聊天、创建私聊与 @提及的输入联想调用 /v1/directory/autocomplete，返回 personId、givenName、familyName、emailAddress 与 avatarUrl。全文消息搜索是 /v1/messages/search。

哪些标识符把聊天室、人员与消息关联起来？

聊天室与私聊用 groupId。人员用 memberId/personId 加 nullableEmail。话题用 topicId；消息用 messageId。分页列表携带 paginationToken 与 hasMoreItems。

与 Google Chat 相似的应用

Slack — Slack 是按频道组织的职场即时通讯工具，支持话题线程和临时通话，常被拿来与 Google Chat 对照。
Microsoft Teams — Microsoft Teams 是带嵌套团队与频道的职场聊天应用，会议最多支持 300 人，面向已使用 Microsoft 365 的组织。
Zoom Workplace — Zoom Workplace 内含 Zoom Chat，可在会议间隙发即时消息，也能从对话一键开会，或为每次会议自动建频道。
Discord — Discord 提供文字频道和可随时进出的语音频道；除了社区之外，也有团队把它当远程办公的沟通工具。
Element — Element 是基于 Matrix 的团队聊天客户端，可部署在自有服务器上，支持加密消息、频道、话题线程和通话。

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

每个项目均签 NDA 与 SOW
3–7 天交付
验收通过后才付款
仅在授权范围内作业

获取报价

Google Chat 数据 API：端点与字段

应用截图

API 端点一览

分页获取首页聊天室与私聊列表

列出聊天室或群聊成员

读取用户在线状态、免打扰与自定义状态

在聊天室创建新话题（线程）

跨聊天室搜索消息

目录中的人员自动补全

数据类别

数据使用场景与案例

Workspace 名册导出

基于在线状态的路由

Chat 话题知识索引

伴生应用中的目录联想

常见问题

与 Google Chat 相似的应用

更多通讯协作类应用

MTS Link

相关主题

需要集成这个 App 的数据 API？

Google Chat 数据 API：端点与字段

应用截图

API 端点一览

分页获取首页聊天室与私聊列表

列出聊天室或群聊成员

读取用户在线状态、免打扰与自定义状态

在聊天室创建新话题（线程）

跨聊天室搜索消息

目录中的人员自动补全

数据类别

数据使用场景与案例

Workspace 名册导出

基于在线状态的路由

Chat 话题知识索引

伴生应用中的目录联想

常见问题

相关应用

与 Google Chat 相似的应用

更多通讯协作类应用

MTS Link

相关主题

需要集成这个 App 的数据 API？