Skip to main content

Google Chat bot setup and usage guide

Last updated 10/03/2026

This document describes how to connect a Google Chat bot to Agentic Engine, and covers admin configuration, user binding, direct message and group chat usage, file handling, and FAQs. The content reflects the current system implementation.

tip

Current recommendation: New Google Chat apps usually use the Google Workspace Add-on mode. Existing projects can still use the legacy Chat app mode. Agentic Engine supports both HTTP callback formats.

If you only need direct messages, you don't need to turn on Join spaces and group conversations. Turn it on only when you need Space @mentions and Thread conversations.

1. Supported capabilities​

CapabilityStatusDescription
Google Chat direct messagesSupportedAfter binding, users can send messages directly. The bot keeps updating its answer by editing the same message.
Space @mentionsOptionalRequires turning on Join spaces and group conversations in the Google Chat API configuration. In group chats, users must explicitly @mention the bot.
Thread conversationsSupportedDifferent Threads in a group chat use separate conversation contexts, and replies go back to the original Thread.
Group chat capability routingSupportedAdmins can configure the default Agent/Team, commands, and keywords. Users can invoke a capability explicitly or have it matched automatically.
Image and document inputSupportedReads images and common office documents that users upload directly to Google Chat. Files shared from Google Drive aren't read.
Generated filesSupportedSent as native attachments after the user completes OAuth file authorization. If the user hasn't authorized or the upload fails, the system automatically falls back to a short-lived HTTPS download link.

2. Before you begin​

  • You have permission to manage the target Google Cloud project and the Google Chat API Configuration
  • You use a Google Workspace account that can access Google Chat
  • Agentic Engine is accessible through a public HTTPS domain
  • You have the System Admin → Channels permission in Agentic Engine
  • For group chats, the Workspace admin allows installing and using Chat apps within the organization
warning

Required checks: Filling in the Service Account JSON alone doesn't complete the setup. You must also configure the Google Chat HTTP callback and the app visibility, and enable group chats and user OAuth as needed.

Instances and identity: Don't connect the same Google Chat Bot identity to multiple channel instances in the same running environment, or to multiple clusters at the same time. Otherwise, you may get duplicate replies, conversation drift, or cancel commands that hit the wrong task.

Differences between the two Service Accounts​

SettingWhere to get itPurpose
Workspace Add-on service account emailGoogle Chat API → Configuration → Connection settingsUsed to verify the OIDC caller identity when Google calls the Agentic Engine Webhook. Fill in only the email here. No key is needed.
Service Account JSON for replying to messagesGoogle Cloud → IAM & Admin → Service Accounts → KeysAgentic Engine uses the chat.bot Scope to call the Google Chat API to send and update bot messages.

These two identities may not be the same account. Don't use the client_email in the JSON to guess or replace the Add-on service account email shown on the Configuration page.

3. Setup overview​

4. Admin setup​

1. Create a Service Account for replying to messages​

  1. In Google Cloud Console, create or select the target project.
  2. Enable the Google Chat API.
  3. Go to IAM & Admin → Service Accounts and create a Service Account used only by this bot.
  4. Create a JSON key for the Service Account and download it immediately.
  5. Keep the JSON as a sensitive credential. Don't send it to group chats or tickets, or commit it to a code repository.

Agentic Engine uses only the https://www.googleapis.com/auth/chat.bot Scope. The JSON is parsed into the required fields and stored encrypted, and the management API never echoes the private key.

2. Create a channel in Agentic Engine​

  1. Go to System Admin → Channels and click New Channel.
  2. Select Google Chat as the channel type, and fill in the channel name, model, and system prompt.
  3. If you use the Workspace Add-on mode, fill in the Workspace Add-on service account email shown on the Google Chat Configuration page. For the legacy Chat app mode, you can leave it empty.
  4. Paste the complete Service Account JSON for replying to messages into the configuration box.
  5. If you want users to receive native attachments under their own identity, turn on Enable user OAuth attachments and fill in the OAuth Client ID and Client Secret.
  6. Save the channel. Edit the channel again and copy the read-only Webhook URL generated by the system.
warning

The Webhook URL contains the channel ID and a random callback token. Always copy the complete URL from the Channels page. Don't type it by hand, truncate it, or change the domain, protocol, basePath, or trailing slash.

When you update the Service Account of the same channel, the Webhook URL doesn't change. If you delete the channel and create it again, a new URL is generated, and you must update the Google Chat API Configuration accordingly.

3. Configure the Google Chat API: Workspace Add-on mode​

When you create a new Chat app, Google Cloud Console may automatically turn on Build this Chat app as a Workspace add-on, and you can't turn it off. This is normal.

  1. Fill in the app name, the HTTPS avatar URL, and the description.
  2. In Connection settings, select Use a common HTTP endpoint URL for all triggers.
  3. Paste the complete Webhook URL from the Agentic Engine Channels page as the HTTP endpoint.
  4. Note down the Service Account email shown in the same area, and enter it in Workspace Add-on service account email in Agentic Engine.
  5. Keep Users can find this app directly in Google Chat and message it selected for direct messages.
  6. If you need Space @mentions and Threads, turn on Join spaces and group conversations. If you only need direct messages, keep it off.
  7. In Visibility, first add test accounts or a Google Group, and set the app status to available to test users.
  8. Save the configuration.

The system currently recognizes Add-on events such as messages, joining or leaving a Space, buttons, Widget updates, and App Commands. Only message events are passed to the Agent. Other events are safely acknowledged but don't trigger a conversation.

4. Configure the Google Chat API: legacy Chat app mode​

  1. In Interactive features, enable Receive 1:1 messages. If you need group chats, also allow joining Spaces.
  2. In Connection settings, select HTTP endpoint URL and enter the complete Webhook URL.
  3. For Authentication audience, select HTTP endpoint URL, and make sure it matches the Webhook URL exactly, character for character.
  4. In Visibility, first limit access to test users or a test group, and save the configuration.

The legacy mode doesn't require Workspace Add-on service account email. Agentic Engine verifies the Google Chat system service identity.

5. Optional: Configure user OAuth native attachments​

The Google Chat Media Upload API doesn't support uploading files with the chat.bot app identity. If you want generated files to be sent as native attachments, you need to configure user OAuth as well.

  1. In the same Google Cloud project, configure the OAuth consent screen and add test users or a publishing scope.
  2. Create an OAuth Client of the Web application type.
  3. Add the complete callback URL of the current site to Authorized redirect URIs: https://{域名}{basePath}/api/google-chat-oauth/callback.
  4. In Agentic Engine Channels, turn on Enable user OAuth attachments and fill in the OAuth Client ID and Client Secret.

The system requests only openid and https://www.googleapis.com/auth/chat.messages.create. The OAuth Token and Client Secret are stored encrypted and never echoed through the management API or regular logs.

6. HTTPS, reverse proxy, and local testing​

  • The Google Chat callback must be a publicly accessible HTTPS URL. You can't use http://localhost or an internal HTTP address directly.
  • For local testing, you can forward traffic to your local service through an HTTPS tunnel such as Cloudflare Tunnel or ngrok.
  • If the public domain changes, update ALLOWED_ORIGINS, restart the service, and update the complete endpoint in the Google Chat API.
  • The reverse proxy must correctly pass Host, X-Forwarded-Host, and X-Forwarded-Proto.

1. Find the app in Google Chat​

  1. Make sure that your current Google Workspace account has been added to the app's Visibility or test user scope.
  2. Open Google Chat and click New chat or Find apps.
  3. Search for the complete app name set in the Google Chat Configuration. Don't search for the Cloud Project ID, the Service Account email, or the Agentic Engine channel name.
  4. Select the result with the App badge and install it. If you only use direct messages, choose to open a 1:1 conversation, and don't add the app to a Space.
Channel statusWhat to do
Admin has enabled user OAuthOpen the account menu in the lower-left corner of Agentic Engine, go to Channel Accounts, select Google Chat, and click Bind and authorize. On the Google page, select the same account you use for Google Chat and grant consent.
Admin hasn't enabled user OAuthIn Channel Accounts, copy the one-time command, such as +bind ABC234, and send it to the app in a direct message in Google Chat. The binding code is valid for 10 minutes and can be used only once.
Bound but files not authorizedIn Channel Accounts, click Authorize files and select the Google account that matches your existing Google Chat binding. If the accounts don't match, the binding isn't changed and no credentials are saved.
tip

Send the binding code only in a direct message to keep the one-time code from leaking. One Google Chat account can be bound to only one Agentic Engine user. If you're told that the account is already bound to another user, first unbind it from the original account.

6. Users: conversations and commands​

Direct messages​

  • After binding succeeds, send plain text to start a conversation.
  • The bot first creates a reply and then keeps updating it until the answer is complete.
  • Send +new to start a new direct message conversation. If a task is running or waiting for an answer, finish the interaction or cancel it first.
  • Send +cancel to stop the current task.

Spaces and Threads​

Available only when the admin has turned on Join spaces and group conversations in the Google Chat Configuration.

  • In a Space, use @bot + question to explicitly wake up the entry bot.
  • The same Thread keeps the same conversation context, and different Threads are isolated from each other.
  • After the admin configures group chat capability routing, regular questions go to the default Agent/Team. You can also use +<command> <question>, @<command> <question>, or configured keywords to select a capability.
  • Send +help, or the Chinese phrase for "capability list", to view the currently available capabilities.
  • Send +cancel to stop the current group chat task.
  • Group chats don't support +new. Send a new task directly, or cancel the current task first.

7. Images and files​

From users to the bot​

  • By default, PNG, JPEG, GIF, and WebP images that users upload directly to Google Chat are supported.
  • By default, txt, md, csv, json, pdf, doc, docx, xls, xlsx, ppt, and pptx are supported.
  • By default, each file can be up to 2MB, each message can have up to 5 attachments, and each attachment download times out after 10 seconds. Admins can adjust these in the server configuration, but not beyond the system's hard limits.
  • Only Google Chat UPLOADED_CONTENT is processed. Files shared from Google Drive are skipped.
  • The actual content of images and PDFs is verified. If the declared type doesn't match the file content, the file is rejected.

From the bot to users​

  • If the user has completed file OAuth authorization, generated files are sent to the original direct message or the original Space/Thread, and appear as sent by the current user through the app.
  • If the user hasn't authorized, the Token refresh fails, or the Google upload fails, the system automatically sends a signed, short-lived HTTPS download link.
  • Download links expire after 10 minutes by default. After a link expires, the source message or run is deleted, or the file content changes, you need to generate the file again.
  • When an answer contains a Markdown table, the system generates result.csv by default. When an answer exceeds the default threshold of 6000 characters or the user explicitly asks for a file, the system generates result.txt.

8. FAQ​

SymptomCheck first
Can't find the appWhether Google Chat and Cloud Console use the same Workspace organization account, whether the account is in Visibility, whether the app status is available, and whether the configuration is saved. Changes may take a few minutes to apply.
App doesn't respond / Webhook 401Whether the Workspace Add-on service account email exactly matches the Configuration page, whether Authentication audience is set to HTTP endpoint in legacy mode, and whether the Webhook URL, HTTPS, reverse proxy, and ALLOWED_ORIGINS are correct.
Webhook 404Whether the channel is disabled or deleted, whether the channel ID and callback token in the URL are still valid, and whether the new URL was updated after the channel was deleted and recreated.
2xx but no bot replyWhether the Service Account JSON for replying to messages is valid, whether the Google Chat API is enabled, and whether the server reports errors when getting the Google OAuth Token, calling the Chat API, or running the model.
Binding failedWhether the binding code was sent in a direct message, is still within its 10-minute validity, and hasn't been used; whether the Google Chat identity is already bound to another user; and whether OAuth used the same Google account that you use for Chat.
Images or documents not parsedWhether the file was uploaded directly by the user rather than shared from Google Drive, whether the type is supported, whether the size, count, or download timeout limits were exceeded, and whether file receiving is enabled on the server.
Only a download link, no native attachmentWhether the admin has configured user OAuth, whether the user has completed Authorize files, and whether the OAuth Token has expired. If the upload fails, the system automatically falls back to a download link.
No response in a SpaceWhether Join spaces and group conversations is turned on, whether the message explicitly @mentions the bot, and whether the Group Chat Space and the Default Agent/Team are configured and verified.

Related pages and next steps

Was this page helpful?
On this page