Google Chat Data API: Endpoints & Fields

Google Chat is Google LLC's team messaging app for Google Workspace — it launched as Hangouts Chat, took the Google Chat name in 2020 and replaced classic Hangouts for personal Google Accounts as well — and it is built around a home inbox that lists every space and direct message with its unread count. Inside it, people hold topic-based conversations in named spaces, start new threads with attachments, formatted text and quoted replies, reply in-thread, trade 1:1 and group direct messages and drop into huddles; a Manage Members sheet shows who belongs to each space and in what role, availability dots and a status row show whether a colleague is active, on Do Not Disturb or has set a custom status with an emoji, a search bar finds past messages across every space or only in one named room, and Start Chat, Create DM and @mention typeahead pull names straight from the company directory. It is a workplace collaboration tool that Workspace organizations use for day-to-day team coordination alongside Gmail, Drive, Calendar and Meet — on Android the same conversations also surface inside the Gmail app — with the Android app listed in markets including the United States, India and Brazil, and it competes with Slack, Microsoft Teams, the chat in Zoom Workplace, Discord and the self-hostable, Matrix-based Element.

Spaces and direct messages are the root objects: each resolves to a groupId and groupName, with a roomAvatarUrl for named rooms and a primaryDmPartnerUserId for DMs, and the inbox feed pages through them by worldSectionType with a per-space unreadCount, a sectionWatermark, a paginationToken and a hasMoreItems flag, bundling the includedMembers in view. Every space carries a roster of members, each with a memberId, nullableEmail, displayName, givenName, familyName, avatarUrl and membershipRole, plus a placeholderUser flag. Layered on top is live availability, looked up for a batch of memberIds and returned as a userStatusMap: a presenceState, a dndStatus with its dndState and dndExpiryTimeMicros, and a customStatus holding statusText, statusEmoji and clearAfterMicros, gated by a presenceShared flag.

The conversations form the message layer: a thread is a topicId, each post a messageId with its messageText, formatting annotations, attachments, an optional quotedMessage, createTimeMicros, creatorMemberId and the originAppId that posted it. Full-text search over that history can be narrowed with fromSelfForSearch or namedRoomForSearch and returns matchedMessages with the source groupName, a text snippet and a resultCount. The Workspace people directory resolves a typed name to a personId, emailAddress, givenName, familyName and avatarUrl, while memberId ties a roster entry to its presence lookup and to the creatorMemberId on every message that member posts.

That structure maps onto concrete internal tooling: IT and security teams export space rosters (groupId, groupName, memberId, nullableEmail, membershipRole) for access reviews; on-call and incident systems page a responder only when presenceState is ACTIVE and dndStatus is not DND, reading the customStatus text as the away reason; knowledge-management teams hydrate internal search indexes with messageId, topicId, groupName and snippet and link each hit back to its space; and helpdesk sidecars resolve a typed name to a personId and emailAddress before opening a Chat DM. openData Studio turns these Google Chat spaces, rosters, presence signals, threads and directory lookups into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Paginate the home world of spaces and DMs

POST /v1/inbox/page opendata

Returns a page of the signed-in user's Chat home (spaces and DMs) with worldSections, worldItems, includedMembers and a paginationToken used by the Merged World / inbox screen.

Auth: OAuth2 Bearer access token for the signed-in Google account (Workspace chat scope bundle). Requests are protobuf-encoded POSTs.

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

List members of a space or group DM

POST /v1/spaces/members osint

Returns the roster for a space or group DM (memberId, nullableEmail, displayName, avatarUrl, membershipRole) used by Manage Members and the people sheet.

Auth: OAuth2 Bearer access token for the signed-in Google account (Workspace chat scope bundle). Requests are protobuf-encoded POSTs.

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
}

Read user presence, DND and custom status

POST /v1/presence/lookup osint

Returns presenceState, dndStatus, customStatus and presenceShared for one or more memberIds, feeding the availability dot on avatars and the status row in a DM.

Auth: OAuth2 Bearer access token for the signed-in Google account (Workspace chat scope bundle). Requests are protobuf-encoded POSTs.

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

Create a new topic (thread) in a space

POST /v1/threads/create opendata

Posts a new thread in a space (messageText, annotations, attachments, messageId) and returns the created topicId used by the message stream.

Auth: OAuth2 Bearer access token for the signed-in Google account (Workspace chat scope bundle). Requests are protobuf-encoded POSTs.

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

Search messages across spaces

POST /v1/messages/search opendata

Runs Hub Search over Chat history (query, filter, sessionId) and returns matchedMessages with messageId, topicId, groupName and a text snippet.

Auth: OAuth2 Bearer access token for the signed-in Google account (Workspace chat scope bundle plus a search query scope). Requests are protobuf-encoded POSTs.

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
}

Autocomplete people in the directory

POST /v1/directory/autocomplete osint

Typeahead over the Workspace directory used by Start Chat / Create DM / @mention, returning personId, displayName, givenName, familyName, emailAddress and avatarUrl.

Auth: OAuth2 Bearer access token for the signed-in Google account (read-only people directory scope).

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

Data categories

spaces
direct-messages
memberships
presence
messages
people-directory

Where teams use this data

Workspace roster export
Pull /v1/inbox/page then /v1/spaces/members per space to build an internal map of groupId, groupName, memberId, nullableEmail, membershipRole and avatarUrl for access reviews.
Presence-aware routing
Call /v1/presence/lookup for on-call memberIds and route a page only when presenceState is ACTIVE and dndStatus is not DND, using customStatus text as the away reason.
Knowledge index of Chat threads
Use /v1/messages/search (query, sessionId, matchedMessages) to hydrate an internal search index with messageId, topicId, groupName and snippet, then open the originating space via groupId.
Directory typeahead in a sidecar app
Proxy the /v1/directory/autocomplete call so a helpdesk tool can resolve query to personId, emailAddress, givenName, familyName and avatarUrl before opening a Chat DM.

Frequently asked questions

How does Google Chat authenticate private data calls?

The client mints an OAuth2 access token for the signed-in Google account with a Workspace chat scope bundle (alongside contacts, drive and calendar access). Calls are protobuf-encoded POSTs authenticated with an Authorization: Bearer header.

Which endpoints expose spaces, members and presence?

/v1/inbox/page pages the home list of spaces and DMs. /v1/spaces/members returns a space roster (memberId, nullableEmail, displayName, membershipRole). /v1/presence/lookup returns presenceState, dndStatus, customStatus and presenceShared.

How does in-app people search work?

Start Chat, Create DM and @mention typeahead call /v1/directory/autocomplete, returning personId, givenName, familyName, emailAddress and avatarUrl. Full-text message search is /v1/messages/search.

What identifiers link a space, a person and a message?

Spaces and DMs use groupId. People use memberId / personId plus nullableEmail. Threads use topicId; posts use messageId. Paginated lists carry paginationToken and hasMoreItems.

Apps similar to Google Chat

Slack — Slack is a workplace messenger organized in channels, with threads and huddles, and Zapier compares it directly with Google Chat for remote teams.
Microsoft Teams — Microsoft Teams is a team chat app with nested teams and channels plus meetings of up to 300 participants, aimed at organizations already on Microsoft 365.
Zoom Workplace — Zoom Workplace includes Zoom Chat for instant messaging between meetings and can start a video call from a thread or create a chat channel for each meeting.
Discord — Discord provides text channels and dedicated always-on audio channels; Zapier notes some teams use it for business coworking as well as communities.
Element — Element is a Matrix-based team chat client you can run on your own server, with encrypted messages, channels, threads, and calls.

More Communication apps

MTS Link
Communication · 14 endpoints

Topics

Google Chat API
chat inbox pagination
space roster endpoint
presence lookup
create thread endpoint
message search endpoint
directory autocomplete
memberId
groupId
presenceState
Workspace Chat data

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Google Chat Data API: Endpoints & Fields

Screenshots

API surface

Paginate the home world of spaces and DMs

List members of a space or group DM

Read user presence, DND and custom status

Create a new topic (thread) in a space

Search messages across spaces

Autocomplete people in the directory

Data categories

Where teams use this data

Workspace roster export

Presence-aware routing

Knowledge index of Chat threads

Directory typeahead in a sidecar app

Frequently asked questions

Related apps

Apps similar to Google Chat

More Communication apps

MTS Link

Topics

Need this app's data API integrated?