Google Chat Toolkit

The Google Chat toolkit connects a Google account to agents and workflows using OAuth and lets you search messages across spaces, list and manage spaces, send and update messages, and add or remove space members. Connecting Google Chat adds Chat scopes to the existing Google OAuth connection without replacing Gmail, Calendar, or Drive access.

Prerequisites

• An active Google Workspace account with access to the Google Chat spaces you intend to use.
• An agent or workflow where you can configure a toolkit.
• Your administrator must have configured a Google OAuth integration before you can connect.

warning

Google Chat nodes use resource names, not short IDs. Always use resource names returned by list or get tools — for example spaces/AAAA for a space and spaces/AAAA/messages/BBB for a message. Use Search Messages to find messages by content; List Messages only lists messages in a space chronologically and is not a text search.

Setup

1. Open an agent or workflow

   Create or open an agent and add the Google Chat toolkit, or add a Google Chat node to a workflow.

2. Connect your Google account

   Select the Google sign-in action when prompted and sign in with the Google Workspace account that has access to the Chat spaces the agent should use.

3. Test with read actions first

   Run List Spaces to confirm access and get space resource names. Use Search Messages to find messages before attempting any write operations.

Available tools

Spaces

Tool	Description
List Spaces	Lists Google Chat spaces the connected account can access. Run this first to get space resource names.
Get Space	Returns details for a single space including display name, type, and URL.
Create Space	Creates a new Google Chat space or group chat.
Update Space	Updates a space's display name or description.

Messages

Tool	Description
Search Messages	Full-text search across Google Chat space history. Supports filtering by space, sender, and time range.
List Messages	Lists messages in a space chronologically. Use for browsing recent messages, not for text search.
Get Message	Returns a single message by resource name.
Send Message	Sends a text message to a space. Optionally reply in an existing thread by providing a thread resource name.
Update Message	Replaces the text of an existing message.
Delete Message	Deletes a message from a space.

Members

Tool	Description
List Members	Lists members of a Google Chat space. Use this before adding or removing members.
Add Member	Adds a user to a space by user resource name or email.
Remove Member	Removes a member from a space using the membership resource name from List Members.

Use cases

• Search a team space for recent mentions of a topic and summarize the findings before sending a follow-up message.
• Post a workflow result, approval outcome, or automated reminder into a designated Google Chat space.
• Create a new project space after a form submission or approval, then add the relevant team members.
• Update a status message in a space after a later workflow step completes successfully.
• Remove a member from a space when project access is revoked or a project ends.

Troubleshooting

Symptom	Likely cause	Fix
Space or message not found	An incorrect resource name was used, or a bare ID was passed instead of a full resource name.	Use List Spaces to get the correct spaces/AAAA resource name. Use List Messages or Search Messages to get message resource names.
List Messages returns no results but messages exist	A text query was passed to List Messages, which does not support text search.	Use Search Messages for content-based search. List Messages only supports createTime filters.
Send Message creates a new thread instead of replying	The thread resource name was missing or incorrect.	Pass the thread value from a prior Search Messages or List Messages response as the Thread Name input. If the thread is missing, Chat falls back to a new thread.
Remove Member fails	A user email was passed instead of a membership resource name.	Use List Members to get the spaces/AAAA/members/123 membership resource name, then pass that to Remove Member.
Add Member fails	The user resource name format is incorrect.	Use users/{email} or users/{id} — a bare email or ID is automatically prefixed with users/.
Google Chat scopes not available after connecting	Chat scopes were added after the initial OAuth connection was established.	Reconnect the Google account to pick up the updated Chat scopes without losing Gmail, Calendar, or Drive access.