openData StudioEnglish
Google Chat 图标

Google Chat 数据 API：端点与字段

Google LLC · 通讯协作

在 Google Play 中打开

Google Chat 的登录态数据 API 是一个 protobuf RPC 面。首页列表通过 /v1/inbox/page 分页（worldSections、worldItems、includedMembers）。聊天室名册来自 /v1/spaces/members（memberId、nullableEmail、membershipRole）。在线状态走 /v1/presence/lookup；新话题提交到 /v1/threads/create；消息搜索通过 /v1/messages/search。目录输入联想是 /v1/directory/autocomplete。

这六个端点都是携带 protobuf 请求体的 POST，请求字段值得细看。收件箱分页器发送 pageSize、worldFilter 与 paginationToken 来遍历首页列表；话题创建提交 messageText、annotations 与 attachments，并取回 topicId；搜索则附加 sessionId 与 searchSurface，让 Hub Search 把分页的 matchedMessages 拼接起来。在线状态应答放在以 memberId 为键的 userStatusMap 中，内含 dndStatus 与 customStatus。

Google Chat 是 Google 的 Workspace 聊天客户端，覆盖聊天室与单聊/群聊。登录态数据 API 为 protobuf RPC：首页分页返回聊天室与私聊（worldSections、worldItems、paginationToken），成员含 memberId，在线状态读取 presenceState，新话题提交 messageText 与 messageId，全文搜索返回 matchedMessages。调用使用 Google 账号的 OAuth2 令牌。

应用截图

  • Google Chat 应用截图 1
  • Google Chat 应用截图 2
  • Google Chat 应用截图 3
  • Google Chat 应用截图 4
  • Google Chat 应用截图 5
  • Google Chat 应用截图 6
  • Google Chat 应用截图 7
  • Google Chat 应用截图 8

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

    依据应用界面推导；端点细节为示意说明，并非实际抓包。

    • 依据应用的首页收件箱流程重建
    • 字段集与 Chat 首页绑定的聊天室及私聊列表一致

  • 列出聊天室或群聊成员

    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 API
  • 聊天收件箱分页
  • 聊天室名册端点
  • 在线状态查询
  • 创建话题端点
  • 消息搜索端点
  • 目录自动补全
  • memberId
  • groupId
  • presenceState
  • Workspace Chat 数据

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

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

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

获取报价