A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Chat API is how an app or AI agent works with a Google Chat workspace: listing and creating spaces, reading and posting messages, managing the people in a space, and adding reactions. Access is granted through OAuth scopes, and a credential acts either as the Chat app itself or on behalf of a signed-in person, which sets what it can see and do. Activity reaches an app through event subscriptions and a Chat app's own endpoint rather than by pushing to a registered URL.
How an app or AI agent connects to Google Chat determines what it can reach. There are several routes, each governed by the OAuth scopes the credential carries and whether it acts as the Chat app itself or on behalf of a signed-in person.
The Chat REST API answers at https://chat.googleapis.com under the v1 path. It covers spaces, members, messages, reactions, attachments, space events, and read state, with each call authorized by OAuth scopes and either app or user authentication.
Google's first-party remote MCP server for Chat answers at https://chatmcp.googleapis.com/mcp/v1 and uses OAuth 2.0. It exposes tools to list messages, search messages, search conversations, and send a message. It is in Developer Preview through the Google Workspace Developer Preview Program, not yet general availability.
Activity in a space, such as a message created or a member joining, is delivered through Google Workspace Events API subscriptions that publish to a Pub/Sub topic. This is how an app receives ongoing events without polling, in place of a per-event webhook URL.
A Chat app receives interaction events, such as being @mentioned, added to a space, or a card click, at its own configured HTTP endpoint or a Pub/Sub topic. This handles direct interactions with the app rather than general space activity.
A service account lets the Chat app act as itself with the chat.bot scope, independently of any person. It suits a bot posting messages, reacting to interaction events, and sending rich cards and interactive widgets. App-managed spaces use the chat.app.* scopes.
An OAuth consent flow lets the app act on behalf of a signed-in person, so each call is limited to what that person can see and do. Some methods, such as listing the spaces a person belongs to, are only available with user authentication.
The Google Chat API is split into areas an agent can act on, such as spaces, the people in them, messages, reactions, and read state. Each area has its own methods and its own scopes, and some grant access to far more than others.
List, read, create, set up, update, and delete spaces, find a direct message or group chat, search spaces a person belongs to, and complete an import.
List and read the members of a space, add a person or app to a space, update a membership, and remove a member.
List, read, create, update, and delete messages in a space, and search messages a person can access.
List the reactions on a message, add a reaction, and remove a reaction.
Read a message's attachment metadata, upload an attachment, and download attachment media.
Read a single space event and list the events in a space, covering messages, memberships, and reactions.
Read and update a person's read state for a space, and read their read state for a thread.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SpacesList, read, create, set up, update, and delete spaces, find a direct message or group chat, search spaces a person belongs to, and complete an import.9 | ||||||
| GET | /v1/spaces | List the spaces the caller is a member of. | read | chat.spaces.readonly | Current | |
User authentication uses chat.spaces.readonly or chat.spaces; app authentication uses chat.bot. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 space reads/min per project; 15/sec per user SourceOfficial documentation ↗ | ||||||
| GET | /v1/{name=spaces/*} | Get the details of a single space. | read | chat.spaces.readonly | Current | |
chat.spaces.readonly or chat.spaces with user auth; chat.bot with app auth. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 space reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/spaces | Create a named space. | write | chat.spaces.create | Current | |
chat.spaces.create or chat.spaces with user auth; chat.app.spaces with app auth. Full URL: https://www.googleapis.com/auth/chat.spaces.create. Acts onspace Permission (capability) chat.spaces.createVersionAvailable since the API’s base version Webhook eventNone Rate limit60 space writes/min per project; 1/sec per user SourceOfficial documentation ↗ | ||||||
| POST | /v1/spaces:setup | Create a space and add members to it in one call. | write | chat.spaces.create | Current | |
Requires user authentication with chat.spaces.create or chat.spaces. Full URL: https://www.googleapis.com/auth/chat.spaces.create. Acts onspace Permission (capability) chat.spaces.createVersionAvailable since the API’s base version Webhook eventNone Rate limit60 space writes/min per project SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/{space.name=spaces/*} | Update a space's details, such as its display name. | write | chat.spaces | Current | |
chat.spaces with user auth; chat.app.spaces with app auth. Full URL: https://www.googleapis.com/auth/chat.spaces. Acts onspace Permission (capability) chat.spacesVersionAvailable since the API’s base version Webhook event space-updatedRate limit60 space writes/min per project SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/{name=spaces/*} | Delete a named space and everything in it. | write | chat.delete | Current | |
Requires the restricted chat.delete scope with user auth, or chat.app.delete with app auth. Deleting a space removes its messages and members. Full URL: https://www.googleapis.com/auth/chat.delete. Acts onspace Permission (capability) chat.deleteVersionAvailable since the API’s base version Webhook eventNone Rate limit60 space writes/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/spaces:search | Search the spaces the calling user is a member of. | read | chat.spaces.readonly | Current | |
Released in Developer Preview on 15 June 2026 for user authentication. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 space reads/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/spaces:findDirectMessage | Find the direct message space with a given person, if one exists. | read | chat.spaces.readonly | Current | |
chat.spaces.readonly or chat.spaces with user auth; chat.bot with app auth. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 space reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/{name=spaces/*}:completeImport | Complete the import process for a space created in import mode. | write | chat.import | Current | |
Requires the restricted chat.import scope with app authentication. Full URL: https://www.googleapis.com/auth/chat.import. Acts onspace Permission (capability) chat.importVersionAvailable since the API’s base version Webhook eventNone Rate limit60 space writes/min per project SourceOfficial documentation ↗ | ||||||
MembersList and read the members of a space, add a person or app to a space, update a membership, and remove a member.5 | ||||||
| GET | /v1/{parent=spaces/*}/members | List the members of a space. | read | chat.memberships.readonly | Current | |
chat.memberships.readonly or chat.memberships with user auth; chat.bot with app auth. Full URL: https://www.googleapis.com/auth/chat.memberships.readonly. Acts onmembership Permission (capability) chat.memberships.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 membership reads/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/{name=spaces/*/members/*} | Get a single membership in a space. | read | chat.memberships.readonly | Current | |
chat.memberships.readonly or chat.memberships with user auth; chat.bot with app auth. Full URL: https://www.googleapis.com/auth/chat.memberships.readonly. Acts onmembership Permission (capability) chat.memberships.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 membership reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/{parent=spaces/*}/members | Add a person or an app as a member of a space. | write | chat.memberships | Current | |
chat.memberships with user auth; chat.app.memberships with app auth. Full URL: https://www.googleapis.com/auth/chat.memberships. Acts onmembership Permission (capability) chat.membershipsVersionAvailable since the API’s base version Webhook event membership-createdRate limit300 membership writes/min per project; 1/sec per user SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/{membership.name=spaces/*/members/*} | Update a membership, such as promoting a member to space manager. | write | chat.memberships | Current | |
chat.memberships with user auth; chat.app.memberships with app auth. Full URL: https://www.googleapis.com/auth/chat.memberships. Acts onmembership Permission (capability) chat.membershipsVersionAvailable since the API’s base version Webhook eventNone Rate limit300 membership writes/min per project SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/{name=spaces/*/members/*} | Remove a member from a space. | write | chat.memberships | Current | |
chat.memberships with user auth; chat.app.memberships with app auth. Full URL: https://www.googleapis.com/auth/chat.memberships. Acts onmembership Permission (capability) chat.membershipsVersionAvailable since the API’s base version Webhook event membership-deletedRate limit300 membership writes/min per project SourceOfficial documentation ↗ | ||||||
MessagesList, read, create, update, and delete messages in a space, and search messages a person can access.7 | ||||||
| GET | /v1/{parent=spaces/*}/messages | List the messages in a space. | read | chat.messages.readonly | Current | |
Requires user authentication with chat.messages.readonly or chat.messages. Full URL: https://www.googleapis.com/auth/chat.messages.readonly. Acts onmessage Permission (capability) chat.messages.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 message reads/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/{name=spaces/*/messages/*} | Get a single message. | read | chat.messages.readonly | Current | |
chat.messages.readonly or chat.messages with user auth; chat.bot with app auth. Full URL: https://www.googleapis.com/auth/chat.messages.readonly. Acts onmessage Permission (capability) chat.messages.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 message reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/{parent=spaces/*}/messages | Post a message to a space. | write | chat.messages.create | Current | |
chat.messages.create or chat.messages with user auth; chat.bot with app auth, which can also send cards and interactive widgets. Full URL: https://www.googleapis.com/auth/chat.messages.create. Acts onmessage Permission (capability) chat.messages.createVersionAvailable since the API’s base version Webhook event message-createdRate limit3,000 message writes/min per project; 1/sec per space SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/{message.name=spaces/*/messages/*} | Update a message's text or cards. | write | chat.messages | Current | |
chat.messages with user auth; chat.bot with app auth. The PUT update method behaves the same with full replacement semantics. Full URL: https://www.googleapis.com/auth/chat.messages. Acts onmessage Permission (capability) chat.messagesVersionAvailable since the API’s base version Webhook event message-updatedRate limit3,000 message writes/min per project SourceOfficial documentation ↗ | ||||||
| PUT | /v1/{message.name=spaces/*/messages/*} | Update a message by full replacement. | write | chat.messages | Current | |
chat.messages with user auth; chat.bot with app auth. This is the PUT form of update, alongside the PATCH form. Full URL: https://www.googleapis.com/auth/chat.messages. Acts onmessage Permission (capability) chat.messagesVersionAvailable since the API’s base version Webhook event message-updatedRate limit3,000 message writes/min per project SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/{name=spaces/*/messages/*} | Delete a message. | write | chat.messages | Current | |
chat.messages deletes the app's own messages; deleting another person's message needs the restricted chat.delete scope, or chat.app.delete with app auth. Full URL: https://www.googleapis.com/auth/chat.messages. Acts onmessage Permission (capability) chat.messagesVersionAvailable since the API’s base version Webhook event message-deletedRate limit3,000 message writes/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/{parent=spaces/*}/messages:search | Search the messages a person can access. | read | chat.messages.readonly | Current | |
Released in Developer Preview on 12 May 2026 for user authentication with chat.messages.readonly or chat.messages. Full URL: https://www.googleapis.com/auth/chat.messages.readonly. Acts onmessage Permission (capability) chat.messages.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 message reads/min per project SourceOfficial documentation ↗ | ||||||
ReactionsList the reactions on a message, add a reaction, and remove a reaction.3 | ||||||
| GET | /v1/{parent=spaces/*/messages/*}/reactions | List the reactions on a message. | read | chat.messages.reactions | Current | |
chat.messages.reactions.readonly, chat.messages.reactions, chat.messages.readonly, or chat.messages with user auth. Full URL: https://www.googleapis.com/auth/chat.messages.reactions. Acts onreaction Permission (capability) chat.messages.reactionsVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 reaction reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /v1/{parent=spaces/*/messages/*}/reactions | Add a reaction to a message. | write | chat.messages.reactions | Current | |
chat.messages.reactions, chat.messages.reactions.create, or chat.messages with user auth. Full URL: https://www.googleapis.com/auth/chat.messages.reactions. Acts onreaction Permission (capability) chat.messages.reactionsVersionAvailable since the API’s base version Webhook event reaction-createdRate limit600 reaction writes/min per project; 5/sec per space SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/{name=spaces/*/messages/*/reactions/*} | Remove a reaction from a message. | write | chat.messages.reactions | Current | |
chat.messages.reactions or chat.messages with user auth. Full URL: https://www.googleapis.com/auth/chat.messages.reactions. Acts onreaction Permission (capability) chat.messages.reactionsVersionAvailable since the API’s base version Webhook event reaction-deletedRate limit600 reaction writes/min per project SourceOfficial documentation ↗ | ||||||
Attachments & mediaRead a message's attachment metadata, upload an attachment, and download attachment media.3 | ||||||
| GET | /v1/{name=spaces/*/messages/*/attachments/*} | Get the metadata of a message attachment. | read | chat.bot | Current | |
Requires app authentication with chat.bot. The attachment bytes are fetched separately through the media download endpoint. Full URL: https://www.googleapis.com/auth/chat.bot. Acts onattachment Permission (capability) chat.botVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 attachment reads/min per project SourceOfficial documentation ↗ | ||||||
| POST | /upload/v1/{parent=spaces/*}/attachments:upload | Upload an attachment that can then be sent in a message. | write | chat.messages.create | Current | |
chat.messages.create or chat.messages with user auth; chat.bot with app auth. Uses the separate upload host. Full URL: https://www.googleapis.com/auth/chat.messages.create. Acts onattachment Permission (capability) chat.messages.createVersionAvailable since the API’s base version Webhook eventNone Rate limit600 attachment writes/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/media/{resourceName=**} | Download the bytes of an attachment by its resource name. | read | chat.bot | Current | |
Requires app authentication with chat.bot. Full URL: https://www.googleapis.com/auth/chat.bot. Acts onattachment Permission (capability) chat.botVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 attachment reads/min per project SourceOfficial documentation ↗ | ||||||
Space eventsRead a single space event and list the events in a space, covering messages, memberships, and reactions.2 | ||||||
| GET | /v1/{name=spaces/*/spaceEvents/*} | Get a single past event in a space. | read | chat.spaces.readonly | Current | |
Needs a scope covering the event's data, such as chat.messages.readonly for message events or chat.memberships.readonly for membership events, with the caller a member of the space. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace event Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 reads/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/{parent=spaces/*}/spaceEvents | List past events in a space, filtered by event type, covering messages, memberships, and reactions. | read | chat.spaces.readonly | Current | |
The filter must name at least one event type, and the credential needs a scope covering that data; the caller must be a member of the space. Full URL: https://www.googleapis.com/auth/chat.spaces.readonly. Acts onspace event Permission (capability) chat.spaces.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 reads/min per project SourceOfficial documentation ↗ | ||||||
Read stateRead and update a person's read state for a space, and read their read state for a thread.3 | ||||||
| GET | /v1/{name=users/*/spaces/*/spaceReadState} | Get a person's read state for a space, showing what they have read. | read | chat.users.readstate | Current | |
User authentication only, with chat.users.readstate.readonly or chat.users.readstate. Full URL: https://www.googleapis.com/auth/chat.users.readstate.readonly. Acts onread state Permission (capability) chat.users.readstateVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 reads/min per project SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/{spaceReadState.name=users/*/spaces/*/spaceReadState} | Update a person's read state for a space, marking it read up to a point. | write | chat.users.readstate | Current | |
User authentication only, with chat.users.readstate. Full URL: https://www.googleapis.com/auth/chat.users.readstate. Acts onread state Permission (capability) chat.users.readstateVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 writes/min per project SourceOfficial documentation ↗ | ||||||
| GET | /v1/{name=users/*/spaces/*/threads/*/threadReadState} | Get a person's read state for a thread. | read | chat.users.readstate | Current | |
User authentication only, with chat.users.readstate.readonly or chat.users.readstate. Full URL: https://www.googleapis.com/auth/chat.users.readstate.readonly. Acts onread state Permission (capability) chat.users.readstateVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 reads/min per project SourceOfficial documentation ↗ | ||||||
Google Chat does not push events to a registered URL the way many APIs do. A Chat app receives interaction events at its own endpoint, and broader activity, like a message being created or a member joining, arrives through Google Workspace Events API subscriptions delivered to a Pub/Sub topic, or by querying the space events methods directly.
| Event | What it signals | Triggered by |
|---|---|---|
google.workspace.chat.message.v1.created | Fires when a message is created in a space the app or subscription can see. Delivered through a Google Workspace Events API subscription, and also returned by the space events list method. | /v1/{parent=spaces/*}/messages |
google.workspace.chat.message.v1.updated | Fires when a message is edited. | /v1/{message.name=spaces/*/messages/*}/v1/{message.name=spaces/*/messages/*} |
google.workspace.chat.message.v1.deleted | Fires when a message is deleted. | /v1/{name=spaces/*/messages/*} |
google.workspace.chat.membership.v1.created | Fires when a member is added to a space, including the app being added. | /v1/{parent=spaces/*}/members |
google.workspace.chat.membership.v1.deleted | Fires when a member is removed from or leaves a space. | /v1/{name=spaces/*/members/*} |
google.workspace.chat.reaction.v1.created | Fires when a reaction is added to a message. | /v1/{parent=spaces/*/messages/*}/reactions |
google.workspace.chat.reaction.v1.deleted | Fires when a reaction is removed from a message. | /v1/{name=spaces/*/messages/*/reactions/*} |
google.workspace.chat.space.v1.updated | Fires when a space's configuration, such as its display name, is changed. | /v1/{space.name=spaces/*} |
Google Chat limits how fast an app or AI agent can call, through per-minute ceilings set per project and tighter per-second ceilings set per space and per user. Reads are allowed far more often than writes, and creating a space is the most restricted action.
Google Chat applies quotas at three levels. Per project, each request type has a per-minute ceiling: reads of messages, memberships, spaces, attachments, and reactions each allow 3,000 per minute, while writes are tighter, with 3,000 message writes, 600 attachment writes, 600 reaction writes, 300 membership writes, and only 60 space writes per minute. On top of that, per-space and per-user ceilings cap bursts to 15 reads per second and 1 write per second, with reaction creation allowed up to 5 per second per space and up to 10 per second during a data import. Going over a quota returns the standard 429 RESOURCE_EXHAUSTED, and the call should be retried with backoff after waiting.
List methods use token-based pagination. A request sets pageSize, and the response returns a nextPageToken that is passed back as pageToken to fetch the next page until the token is absent. For listing spaces the default pageSize is 100 and the maximum is 1,000, and a value above 1,000 is reduced to 1,000. When a filter is used, the same filter value must be sent with each page token.
Requests and responses are JSON over HTTPS. Message attachments are uploaded and downloaded through a separate media endpoint rather than inline in the message body. The reference does not state a single global request size limit; individual fields and uploads set their own ceilings.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | The request is malformed, such as a missing required field, a bad resource name, or an invalid filter on the space events methods. | Correct the named field or parameter and resend; do not retry the same request unchanged. |
| 401 | UNAUTHENTICATED | The OAuth credential is missing, invalid, or expired, so the request is not authenticated. | Obtain or refresh a valid OAuth token and send it in the Authorization header. |
| 403 | PERMISSION_DENIED | The caller is authenticated but not allowed. The token may lack the required scope, the person may not be a member of the space, or a Workspace administrator has not granted the one-time approval needed for a chat.app.* scope. | Grant the missing scope, add the caller to the space, or have an administrator approve the app's scopes. |
| 404 | NOT_FOUND | The named resource does not exist, or the caller cannot see it. A space, message, or membership name that the credential has no access to returns 404. | Confirm the resource name is correct and that the credential has access to it. |
| 429 | RESOURCE_EXHAUSTED | A quota was exceeded, such as the per-minute project ceiling or the per-second per-space or per-user ceiling. | Slow down and retry with exponential backoff after waiting; request a quota increase if the limit is hit consistently. |
| 500 | INTERNAL | An unexpected error occurred on Google's side while handling the request. | Retry with exponential backoff; if it persists, report it through Google's support channels. |
Google Chat exposes a single dated major version, v1, in the request path. New methods and fields ship continuously through dated release notes rather than a new version number, so an integration built on v1 keeps working as features are added.
The Google Chat API exposes a single dated major version, v1, in the request path. Rather than minting new version numbers, Google ships new methods and fields continuously through dated release notes, often first in a Developer Preview and later as generally available. Recent additions include searching messages and spaces, quoting and forwarding messages, message pins, and a first-party MCP server.
Through the first half of 2026, v1 gained several capabilities without a new version number. Message search arrived in Developer Preview, app-authenticated apps gained control over a message's notification, and read-state subscriptions were added in preview, alongside the launch of the first-party MCP server.
Features often land in a Developer Preview before reaching general availability, so a method can exist for preview-program projects before it is generally available.
Google Chat API release notes ↗Bollard AI sits between a team's AI agents and Google Chat. Grant each agent exactly the access it needs, read or write, space by space, and every call is checked and logged.