←back to manuals

Google Chat Integration

Integrate ChatBotKit with Google Chat to deploy intelligent AI agents directly within Google Workspace spaces, enabling seamless collaboration through direct messages and space conversations.

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 Chat API enabled and a service account with the Chat App role.

Webhook Configuration

After creating the integration, configure this URL as the HTTP endpoint in your Google Cloud Console Chat API settings under "Connection settings":

https://api.chatbotkit.com/v1/integration/googlechat/{googlechatIntegrationId}/event

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

Google Chat Queue Processing and Background Operations

The Google Chat queue system handles asynchronous processing of message events and setup operations. This background processing architecture enables complex AI conversations without blocking the Google Chat webhook endpoint's 30-second response requirement.

The queue processes two primary event types: interaction events that handle user messages and AI conversation processing, and setup events that validate service account credentials.

Interaction Event Processing

When a user sends a message in Google Chat, the event endpoint queues an interaction event containing the sender info, space name, thread name, and message text. The queue handler processes these events asynchronously, managing conversation state, session management, and AI response generation.

Session Management

Sessions are stored in Redis with keys in the format googlechat-session-{integrationId}-{senderName}-{spaceName}, ensuring each user in each space has an independent conversation context. Users can restart their session by sending ///restart, ///reset, or ///new.

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.

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

Configure this URL in Google Cloud Console → APIs & Services → Chat API → Configuration → Connection settings → HTTP endpoint URL:

https://api.chatbotkit.com/v1/integration/googlechat/{googlechatIntegrationId}/event

Replace {googlechatIntegrationId} with your actual integration ID.

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

When a projectNumber is configured, all incoming requests are verified against Google Chat's published public keys. Without a projectNumber, verification is skipped (suitable for development/testing only).

Auto-Respond Configuration

The autoRespond field controls when the bot responds in spaces (not DMs):

  • null / empty: Only respond to direct messages
  • @all: Respond to all messages in all spaces
  • @agent : Use an AI agent to decide whether to respond
  • Custom text: Use LLM evaluation against the provided criteria

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.

Fetching a Google Chat Integration

Retrieve the configuration for a single Google Chat integration. The serviceAccountKey field is masked as "********" if configured.

Setting Up the Google Chat Integration

Validate the Google Chat integration credentials by verifying that the service account key can obtain an OAuth2 access token from Google.

This endpoint is called automatically after create and update operations.

Updating a Google Chat Integration

Update the configuration for an existing Google Chat integration. Changes take effect immediately. After updating, a setup validation is triggered automatically.

Listing Google Chat Integrations

Retrieve a paginated list of all Google Chat integrations configured in your ChatBotKit account. Sensitive credentials are masked as "********".

googlechatintegrationwebhookbot