Google Chat Integration

ChatBotKit's Google Chat integration enables you to deploy AI agents directly within Google Chat spaces and direct messages, allowing teams to interact with intelligent assistants through natural conversations.

Creating a Google Chat Integration

Before creating the integration, you need a Google Cloud project with the Google Chat API enabled and a service account in that same project. The Google Chat API is enabled via APIs & Services → Library in the Google Cloud Console (search "Google Chat API" → Enable) - it does not appear elsewhere in the console until that step is done. The service account itself does not need an IAM role: it is recognised as your Chat app because it lives in the same project as the Chat API configuration.

To create the integration, send a POST request with your Google Cloud credentials:

The response includes the integration ID needed for the next step:

Webhook Configuration

After creating the integration, configure this URL as the HTTP endpoint in your Google Cloud Console under APIs & Services → Enabled APIs & services → Google Chat API → Configuration → Connection settings:

Replace {googlechatIntegrationId} with the ID returned from this endpoint.

To use the bot in a Google Chat space or group conversation, you must also add the Chat app to that specific space in Google Chat. Open the space, use "Manage members" or "Add people & apps", search for the app by its App name, and add it. The Google Cloud "Join spaces and group conversations" setting only makes the app eligible to join spaces; it does not automatically install the app into existing spaces.

Validating Integration Setup

Validate the Google Chat integration credentials by verifying that the configured service account key can be used to authenticate with Google Chat. This ensures the integration has the proper permissions to send messages back to Google Chat spaces and direct messages on behalf of your bot.

This endpoint is primarily called automatically after create and update operations, but can also be invoked manually to troubleshoot credential issues or verify configuration after making changes outside of the standard update flow.

Validation Checks

The setup validation checks that the configured service account key is readable, belongs to a usable Google Cloud service account, and can be used by ChatBotKit to send messages for the Chat app.

If validation fails, the endpoint returns a 409 Conflict error with a descriptive message explaining the specific issue found.

When to Use Setup Validation

After Manual Credential Updates: If you have updated the service account key through the update endpoint or made other credential changes, run setup validation to confirm the new credentials work correctly before relying on them for production traffic.

Troubleshooting Message Delivery Failures: When the bot stops responding in Google Chat spaces, use setup validation to rule out credential expiry or permission changes as the root cause.

Troubleshooting Space Responses: 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 through Google Chat's "Add people & apps" or "Manage members" flow. Google Chat does not send space interactions to apps that are merely enabled in the Cloud configuration but not installed in the space.

Verifying New Service Accounts: After rotating service accounts or creating new ones in Google Cloud Console, validate the credentials are properly configured for the Chat app's Google Cloud project.

Response

Success Response (200 OK):

Error Response (409 Conflict - Invalid JSON):

Example Error Response (409 Conflict):

Troubleshooting Setup Failures

Invalid JSON Format: Download a fresh service account key JSON file from Google Cloud Console (IAM & Admin - Service Accounts - Keys) and provide the complete file contents as the serviceAccountKey field.

Incomplete Service Account Key: Service account keys downloaded from Google Cloud Console contain all required values. Keys manually constructed or partially copied may be incomplete.

Credential Validation Failure: Ensure the Google Cloud project has the Chat API enabled and the service account belongs to that same project. No IAM role assignment is required for a Chat-app service account. Also verify the service account key has not been revoked or expired.

Note: When the integration was created without a service account key, setup validation is skipped as a no-op. The bot can still receive messages but cannot send replies without valid credentials.

Updating a Google Chat Integration

Modify the configuration of an existing Google Chat integration. All fields are optional - only send the fields you want to change. The integration continues to handle messages without interruption while the update is applied. After a successful update, a setup validation event is automatically triggered to verify the new configuration.

Updatable Fields

• name (string): Human-readable label for the integration
• description (string): Description of the integration's purpose
• blueprintId (string): Associate the integration with a blueprint resource
• botId (string): Change the bot that handles incoming Google Chat messages
• serviceAccountKey (string or null): Google Cloud service account key JSON. Send "********" to preserve the existing key, or send a new JSON string to replace it. Set to null to clear the credential.
• projectNumber (string or null): Google Cloud project number used for request verification. This is the numeric project identifier (typically 12 digits), distinct from the human-readable project ID. You can find it on the Chat API Configuration page under "Application info" as "Project number (App ID)", on the Google Cloud Console home dashboard under "Project info", in the project picker drop-down, or via gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)".
• contactCollection (boolean): Enable or disable contact collection for direct message conversations. Shared spaces and group conversations are not associated with contacts.
• sessionDuration (number or null): Session timeout in milliseconds. Set to null for unlimited sessions. Maximum is one month.
• attachments (boolean): Enable or disable uploaded file processing. Uploaded Google Chat files are stored as conversation attachments when this is enabled. Google Drive-backed attachments are skipped.
• autoRespond (string or null): Reserved auto-respond behavior setting. Google Chat interaction webhooks only deliver direct messages and explicit app interactions in spaces, such as @mentions; they don't deliver every message posted in a space.
• allowFrom (string or null): Restrict which sender types receive bot responses
• meta (object): Custom metadata key-value pairs attached to the integration

Setup Validation

After each update, the system automatically validates the setup for the integration. This ensures that credential or configuration changes are applied and verified without requiring a manual re-setup step.

Example: Updating Credentials

To rotate the service account key while keeping other settings unchanged:

The response returns the integration ID on success:

Listing Google Chat Integrations

Retrieve a paginated list of all Google Chat integrations configured in your ChatBotKit account. Use this endpoint to audit existing integrations, build management dashboards, or synchronize integration state with external systems.

The list endpoint returns results in descending order by default (newest first). You can control the ordering using the order query parameter and page through results using the cursor returned in each response.

Pagination

Use the cursor and take query parameters to page through large result sets. Pass the cursor value from a previous response to fetch the next page. Set take to control how many items are returned per page.

Filtering by Metadata

You can filter integrations by metadata key-value pairs using the meta query parameter with deep object notation:

Response Fields

Each integration object in the response includes:

• id: Unique identifier for the integration
• name: Human-readable label for the integration
• description: Optional description of the integration's purpose
• blueprintId: Associated blueprint ID (if linked)
• botId: The bot that handles incoming Google Chat messages
• serviceAccountKey: Returns "********" if configured, null if not set
• projectNumber: Google Cloud project number used for JWT token verification
• contactCollection: Whether contact records are collected for direct message conversations
• sessionDuration: Conversation session timeout in milliseconds
• attachments: Whether uploaded Google Chat files are processed as conversation attachments
• autoRespond: Auto-respond mode setting for the integration
• allowFrom: Restriction on which senders this bot will respond to
• meta: Custom metadata object attached to the integration
• createdAt: ISO timestamp of when the integration was created
• updatedAt: ISO timestamp of the last modification

Security Note: The serviceAccountKey field is intentionally masked in list responses to prevent credential exposure. To verify whether credentials are configured, check whether the field returns "********" rather than null.

Example Response

Fetching a Google Chat Integration

Retrieve the complete configuration details for a specific Google Chat integration by its unique ID. Use this endpoint to inspect current settings, verify feature enablement, or check resource associations before making updates.

Replace {googlechatIntegrationId} with the ID returned when the integration was created, or obtained from the list endpoint.

Response Fields

The response includes all configuration fields for the integration:

• id: Unique identifier for the integration
• name: Human-readable label for the integration
• description: Optional description of the integration's purpose
• blueprintId: Associated blueprint ID (if linked)
• botId: The bot that handles incoming Google Chat messages
• serviceAccountKey: Returns "********" if configured, null if not set
• projectNumber: Google Cloud project number used for JWT token verification
• contactCollection: Whether contact records are collected for direct message conversations
• sessionDuration: Conversation session timeout in milliseconds (null for unlimited)
• attachments: Whether uploaded Google Chat files are processed as conversation attachments
• autoRespond: Auto-respond mode setting for the integration
• allowFrom: Restriction pattern for which sender types receive responses
• meta: Custom metadata key-value pairs attached to the integration
• createdAt: ISO timestamp of integration creation
• updatedAt: ISO timestamp of last modification

Security Considerations

The serviceAccountKey field is masked and returned as "********" when a key has been configured. This prevents accidental exposure of sensitive Google Cloud credentials in API responses. To check whether credentials are set, verify that the field is non-null rather than inspecting the value.

When updating the integration, send the sentinel value "********" to preserve the existing key, or send a new JSON key string to replace it.

Example Response

If the integration does not exist or belongs to another account, the endpoint returns a 404 Not Found or 403 Forbidden error respectively.

Deleting a Google Chat Integration

Permanently remove a Google Chat integration from your ChatBotKit account. This action is irreversible and immediately stops the bot from responding to events from Google Chat spaces and direct messages. The associated bot and any other linked resources are not affected - only the integration record itself is removed.

Replace {googlechatIntegrationId} with the ID of the integration you want to remove. You can retrieve the ID from the list endpoint or from the response when the integration was originally created.

What Happens After Deletion

Once deleted, any incoming webhook events from Google Chat targeting this integration will no longer be processed. If your Google Chat app is still configured to send events to this endpoint, those requests will return an error. You should update or remove the Google Chat app configuration in Google Cloud Console to stop sending requests to the deleted integration.

The response confirms deletion by returning the ID of the removed integration:

If the integration does not exist or belongs to another account, the endpoint returns a 404 Not Found or 403 Forbidden error respectively.

Event Webhook Endpoint

Handle real-time events from Google Chat including messages and space membership changes. This webhook endpoint is the core of the Google Chat integration, receiving and processing all events that trigger bot responses.

The event endpoint must be configured as the HTTP endpoint URL in your Google Cloud Console Chat API settings under "Connection settings".

Webhook URL Configuration

The endpoint URL has the form:

Replace {googlechatIntegrationId} with your actual integration ID.

To register it in Google Cloud Console:

1. Enable the Google Chat API via APIs & Services → Library (search "Google Chat API" → Enable). Until the API is enabled it does not appear anywhere else in the console.
2. Go to APIs & Services → Enabled APIs & services → Google Chat API → Configuration tab.
3. 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 page 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.
4. Under Connection settings, set the endpoint type to HTTP endpoint URL (the other option is Apps Script - you want HTTP).
5. Select Use a common HTTP endpoint URL for all triggers so that a single URL field appears, then paste the endpoint URL above into it.
6. Under Functionality, enable Join spaces and group conversations if you want the bot to operate in multi-user spaces in addition to direct messages.
7. Optional: under Commands, add slash commands, quick commands, or message actions. Slash commands include the command text and any arguments. Quick commands and message actions are delivered by command ID, so add bot instructions for the generated command token, such as /googlechat-quick-command-444. Command responses are sent privately to the user who invoked them.
8. 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.
9. Save the configuration.
10. 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 interactions 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 back to the Visibility section and make sure either (a) the "specific people and groups" option is ticked with at least your own email in the list, or (b) the "available to everyone in your domain" option 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 hides the domain-wide visibility option entirely and shows a notice beginning "Your admin's Google Workspace Marketplace setting requires app allowlisting." In that case the specific people and groups list is capped at 5 email addresses (intended for development/testing); group/domain visibility has no effect until either the app is published to the Google Workspace Marketplace (see Google's "Publish Google Chat apps" guide) or your Workspace admin allowlists the app in Workspace Marketplace admin settings. For internal-only bots, asking the admin to allowlist the app is usually simpler than publishing it.

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. Without that exception, internal Chat apps can receive mention events but asynchronous replies may 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. 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.

Event Types

MESSAGE: Sent when a user sends a message to the Chat app. The bot processes the message asynchronously and replies in the same space/thread.

ADDED_TO_SPACE: Sent when the Chat app is added to a space or a direct message is initiated. The bot immediately responds with a welcome message.

REMOVED_FROM_SPACE: Sent when the Chat app is removed from a space. The event is logged and no response is sent.

JWT Verification

Google Chat signs webhook requests sent to this endpoint. Configure the integration with the Google Cloud Project Number from the same project as your Chat app so ChatBotKit can verify incoming requests. Leaving the Project Number empty disables request verification and should only be used for local development or manual testing.

Space Message Delivery

Google Chat interaction webhooks only deliver direct messages and explicit app interactions in spaces, such as @mentions, slash commands, or other configured app interactions. They do not deliver every message posted in a space.

The integration can't make Google Chat send messages that this interaction webhook doesn't receive. Reacting to every message in a space would require a separate Google Workspace Events API subscription flow.

Commands

Google Chat supports slash commands, quick commands, and message actions. ChatBotKit can receive all three command types through the same interaction endpoint and routes command responses privately to the user who invoked them.

Slash commands include the command name and argument text in the message that ChatBotKit sends to the bot. For example, a slash command such as /support with the text billing question is handled as /support billing question. Configure the bot with instructions for each slash command that should trigger a specific workflow.

Quick commands and message actions are different: Google Chat sends the command ID and command type, but not the display name or description from the Google Cloud configuration. ChatBotKit therefore passes a stable command token to the bot, such as /googlechat-quick-command-444 or /googlechat-message-action-444. Add bot instructions that map each token to the intended behavior. For message actions, selected message text is included after the command token when Google provides it.

Context Security

Google Chat direct messages are treated as trusted 1:1 conversation surfaces. This lets private, account-specific actions continue in a direct message when a user has connected the required credentials.

Multi-user spaces and group conversations are treated as shared surfaces. The bot can still answer messages there, but private user context is not used for actions that require user-specific credentials, and contacts are not attached to conversations created in those shared surfaces. If an action needs a user's private credentials, the user should continue the flow in a direct message.

Unknown or missing Google Chat space types are handled conservatively and are treated like shared spaces rather than trusted direct messages.

File Attachments

When attachments is enabled, uploaded files included in Google Chat messages are downloaded and stored as conversation attachments before the bot receives the user's text. This makes documents, images, and other uploaded files available to attachment-aware bot workflows.

Media-only messages are processed for attachments but do not trigger a bot reply unless the user also sends text. This avoids unsolicited responses when a user uploads a file without a prompt.

Google Drive-backed attachments are not downloaded by this flow. Google exposes those through Drive-specific references rather than Chat uploaded media, so they are skipped safely.

Session Management

Each unique sender within a space maintains their own conversation session. Sessions expire based on the configured sessionDuration (default: 1 day). Users can reset their session by sending ///restart, ///reset, or ///new.

Initiating a Google Chat Message

The Google Chat initiate endpoint sends a message from the configured Chat app to an existing Google Chat space. The target can be a direct message or a shared space that the Chat app can access.

To send a direct message by user, provide the user's Google Chat identifier as space:

Required parameters:

• text - The message body to send
• space - The Google Chat space resource name where the app should post, or a Google Chat user identifier for a direct message

Prerequisites: The Google Chat integration must have a bot configured and a service account key with access to the Chat API. The Chat app must already have access to the target space or direct message.

Background Processing

Google Chat requires webhook responses within 30 seconds, which is too short for many AI conversations. To handle this, messages are processed asynchronously in the background, allowing the bot to acknowledge Google Chat immediately and deliver its reply when ready.

Conversation Sessions

Each user in each Google Chat space has their own independent conversation context, so a single user can hold separate ongoing conversations across different spaces without them mixing.

Users can restart their conversation at any time by sending ///restart, ///reset, or ///new, which clears the current context and starts a fresh session.