Google Chat

The Google Chat integration allows you to deploy a ChatBotKit AI bot directly into Google Chat spaces and direct messages. Users in your Google Workspace can @mention the bot in spaces or start a direct message conversation, and the bot will respond using the knowledge and instructions you have configured.

Each integration is tied to its own Google Cloud project and Chat app, so multiple users can independently run their own bots - each with their own credentials, configuration, and conversation history.

What You Can Do

With the Google Chat integration, you can:

• Space Conversations: Deploy the bot into any Google Chat space where it gets added, responding when users explicitly interact with the app, such as by @mentioning it
• Direct Messages: The bot automatically responds to direct messages from users without needing to be @mentioned
• Thread Awareness: In spaces, the bot recognises threads and maintains conversation context within a thread so replies stay coherent
• Commands: Configure slash commands, quick commands, or message actions that send private responses back to the invoking user
• File Attachments: When enabled, uploaded files sent to the Chat app are made available to the bot as conversation attachments
• Sender Filtering: Restrict which Google Workspace users can interact with the bot using the Allowed Senders field - useful for internal or team-specific bots
• Multiple Instances: Create multiple Google Chat integrations pointing at different Google Cloud projects, allowing you to run separate bots for different teams or use cases
• Automated Responses: Provide 24/7 AI-powered support inside your organisation's existing Google Chat workflow

How It Works

When a user sends a message to your Chat app - either by @mentioning it in a space or by sending a direct message - Google Chat sends it to the HTTP endpoint URL shown on this page. ChatBotKit verifies the request, runs the message through your configured bot, and sends the reply back to Google Chat using the service account credentials you provide.

The integration maintains per-user conversation context so each person talking to the bot gets a coherent, session-aware experience. Sessions expire based on the session duration you configure.

Users can reset their current conversation by sending ///restart, ///reset, or ///new.

Getting Started

1. Create the Integration: Give it a name and select the bot that will handle conversations
2. Note the HTTP Endpoint URL: After saving, this page shows your unique webhook URL - copy it
3. Set Up a Google Cloud Project: Go to Google Cloud Console and create a project
4. Enable the Google Chat API: Open APIs & Services → Library, search for "Google Chat API", and click Enable. The API will not appear under APIs & Services anywhere else until this step is done
5. Configure the Chat API: Once enabled, go to APIs & Services → Enabled APIs & services → Google Chat API → Configuration tab, then set the HTTP Endpoint URL to your ChatBotKit endpoint and enable the functionality you need
6. Create a Service Account: Under "IAM & Admin → Service Accounts" in the same Google Cloud project, create a service account and download a JSON key. No IAM role assignment is required - Google recognises the service account as part of the same Chat app project
7. Fill In Credentials: Paste the JSON key into the Service Account Key field and enter your Google Cloud Project Number. The Project Number is a numeric identifier (typically 12 digits) distinct from the human-readable project ID. The easiest place to copy it is the Chat API Configuration page itself (shown under "Application info" as "Project number (App ID)"); it is also on the Google Cloud Console home dashboard under "Project info" or in the project picker drop-down.
8. Save and Setup: Click Save, then click Setup to verify the connection
9. Add the App in Google Chat: Start a direct message with the app to test DMs. For spaces or group conversations, open the target space in Google Chat, choose Manage members or Add people & apps, search for the Chat app by its App name, and add it to that specific space. Enabling "Join spaces and group conversations" only makes the app eligible to be added; it does not automatically install it into any space.

Admin note: Workspace or Google Cloud admins can also find the project number with gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)".

Connect Google Chat to ChatBotKit

The HTTP Endpoint URL is how Google Chat delivers interaction events to ChatBotKit. Configure it in the Google Cloud Console:

1. Open Google Cloud Console and navigate to your project
2. Enable the Google Chat API: APIs & Services → Library → search "Google Chat API" → Enable (required before the API surfaces anywhere else)
3. Go to APIs & Services → Enabled APIs & services → Google Chat API → Configuration
4. Under Application info, fill in the required fields: App name (display name shown to users in Chat), Avatar URL (a publicly reachable https:// image URL - Google Drive sharing links do not work), and Description. The configuration cannot be saved while any of these are empty. The Project number (App ID) shown here is also the value to paste into the Project Number field on the ChatBotKit integration page
5. Under Connection settings, set the endpoint type to HTTP endpoint URL (the other option is Apps Script - you want HTTP)
6. Select Use a common HTTP endpoint URL for all triggers so that a single URL field appears, then paste your ChatBotKit endpoint into it
7. Under Functionality, enable Join spaces and group conversations if you want the bot in multi-user spaces
8. Optional: under Commands, add slash commands, quick commands, or message actions. Use clear names and descriptions, and add matching instructions to your bot so it knows how to respond to each command
9. Under Visibility, either select Make this Chat app available to specific people and groups in your domain and enter at least one email address (the configuration cannot be saved while this list is empty), or choose to make it available to everyone in your Workspace domain
10. Save the configuration
11. In Google Chat, add the app to each space where you want it to respond: open the space, choose Manage members or Add people & apps, search for the app's App name, and add it. For direct messages, start a new chat with the app instead.

Google Chat only sends space events after the Chat app has been added to that specific space. The Join spaces and group conversations setting allows the app to be added to spaces, but it does not add the app for you.

⚠️ Gotcha - if you cannot find the bot when searching in Google Chat

Google Chat Visibility is deny-by-default: if no one is on the allowlist, nobody can discover or add the app. Go to APIs & Services → Enabled APIs & services → Google Chat API → Configuration → Visibility and make sure one of these is true:

• "Make this Chat app available to specific people and groups in your domain" is ticked and at least your own email is in the list, or
• "Make this Chat app available to everyone in your domain" is ticked.

Toggling the specific-people option off without enabling the domain-wide option makes the bot completely undiscoverable - searching by its App name in + New chat or "Add people & apps" will return no results. You must also be signed into Google Chat as a user in the same Workspace domain as the project; personal @gmail.com accounts cannot see Chat apps hosted in a Workspace project.

⚠️ Gotcha - if the "available to everyone in your domain" option is missing

If your Workspace admin has enabled the Marketplace allowlisting policy, Google Chat will hide the domain-wide visibility option entirely and show a notice that begins with "Your admin's Google Workspace Marketplace setting requires app allowlisting." In that case:

• You can still use the specific people and groups option, but the list is capped at 5 email addresses (intended for development/testing).
• To make the app available beyond those 5 users, the app must either be published to the Google Workspace Marketplace (see Google's Publish Google Chat apps guide), or your Workspace admin must explicitly allowlist the app in Workspace Marketplace admin settings.
• Group/domain visibility settings configured here have no effect until one of those happens - even if you can tick them, they are ignored by the allowlisting policy.
• Also check Admin Console → Apps → Google Workspace Marketplace apps → Settings → Manage access to apps. If Don't allow users to install and run apps from the Marketplace is enabled, turn on Allow exception for internal apps. Users can install and run any internal app.

For internal-only bots, the simplest path is usually to ask your Workspace admin to allowlist the app rather than publishing to the public Marketplace. Without the internal-app exception above, the app can still receive mention events, but asynchronous replies can fail with 403 PERMISSION_DENIED: "This organization's administrator must allow users to install this Chat app."

⚠️ Gotcha - spaces must explicitly include the app

If direct messages work but the bot does not respond in a space, confirm that the Chat app has been added to that exact space. Open the space in Google Chat, use Manage members or Add people & apps, search for the app's App name, and add it.

The Google Cloud Join spaces and group conversations checkbox is required for space support, but it only controls whether the app can be added. It does not automatically place the app into existing spaces.

Integration Settings

Name: A human-readable label used only inside ChatBotKit. It does not change the app's display name in Google Chat.

Description: An internal note that helps you remember what the integration is for, especially when you manage several Chat apps.

Bot: The ChatBotKit bot that handles incoming Google Chat messages.

Service Account Key: The JSON key for a service account in the same Google Cloud project as the Chat API configuration. ChatBotKit uses it to send replies for your Chat app. The key is stored encrypted and is never shown in full after saving.

Project Number: The numeric Google Cloud project identifier, also shown as Project number (App ID) on the Chat API Configuration page. Setting it enables request verification for production traffic.

Contact Collection: When enabled, ChatBotKit creates contact records from direct message conversations using the Google Chat sender identity. Contacts are not associated from shared spaces or group conversations.

Attachments: When enabled, uploaded Google Chat files are downloaded and made available to the bot as conversation attachments. Google Drive-backed attachments are skipped because they use a separate Drive file reference.

Session Duration: Controls how long a user's conversation context is preserved. By default this is one day. Set a longer duration for workspaces where users often return to the same conversation after long pauses.

Auto-Respond Configuration: Google Chat only sends direct messages and explicit app interactions in spaces. This setting cannot make the bot see every unmentioned message in a space.

Allowed Senders: Restricts who can interact with the integration. Enter one entry per line, using a Google Chat user identifier, a display name, or * to allow all users. Leave the field empty to deny all users.

Best Practices

Control Who Can Interact: Use the Allowed Senders field to restrict access for internal bots. This prevents unexpected usage if the Chat app is accidentally added to a public space.

Understand Space Message Delivery: Google Chat only sends direct messages and explicit app interactions in spaces, such as @mentions. It does not send every message posted in a space. Use the Allowed Senders filter to control who can interact with the bot.

Context Security: Direct messages are better suited for private account-specific tasks. Multi-user spaces and group conversations are shared contexts, so some private actions may require the user to continue in a direct message.

Contact Collection: When enabled, contact records are collected from direct message conversations. Shared spaces and group conversations are not associated with contacts.

File Attachments: Enable Attachments if users need to send files for the bot to inspect. Uploaded Google Chat files are supported; Google Drive-backed attachments are skipped.

Session Duration: Google Chat conversations can have long gaps between messages. Consider setting a longer session duration (such as 4–8 hours) so users can return to a conversation without losing context.

Multiple Bots: You can create several Google Chat integrations - each pointing to a different Google Cloud project and Chat app - to run separate bots for different teams, languages, or purposes.

Practical Use Cases

Internal Knowledge Base: Deploy a bot in your company's Google Chat that answers questions about internal processes, HR policies, or technical documentation - available to employees directly inside Workspace.

IT Helpdesk: Let employees ask IT questions in a dedicated helpdesk space. The bot handles common troubleshooting steps and escalates to a human when needed.

Onboarding Assistant: Add the bot to onboarding spaces to help new employees find information, understand company processes, and get answers to frequently asked questions.

Project Space Bot: In a project-specific space, use the bot to field questions about project status, documentation, or meeting notes, keeping the team informed without manual effort.

Developer Support: Deploy a bot in your engineering spaces that answers questions about your codebase, APIs, or runbooks, surfacing information from your dataset directly in the conversation.

The Google Chat integration lets you bring conversational AI into the place where your team already communicates, without asking them to change tools or workflows.