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

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

POST /api/v1/integration/googlechat/create
Content-Type: application/json

{
  "name": "Google Chat Bot",
  "description": "AI assistant for our workspace",
  "botId": "bot_abc123",
  "serviceAccountKey": "{...service account JSON string...}",
  "projectNumber": "123456789"
}

http

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

{ "id": "googlechat_abc123..." }

json

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.

Validating Integration Setup

Validate the Google Chat integration credentials by verifying that the configured service account key can successfully obtain an OAuth2 access token from Google's authentication endpoints. 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.

POST /api/v1/integration/googlechat/{googlechatIntegrationId}/setup
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{}

http

Validation Checks

The setup validation performs the following checks against the configured service account key:

Service Account Key Format:

  • Verifies the key is valid JSON that can be parsed
  • Checks that client_email and private_key fields are present
  • Both fields are required for Google's JWT-based OAuth2 flow

OAuth2 Token Exchange:

  • Constructs a signed JWT using the service account's private key
  • Submits the JWT to Google's token endpoint with the chat.bot scope
  • A successful token exchange confirms the credentials are valid and the Chat API is enabled for the associated Google Cloud project

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.

Verifying New Service Accounts: After rotating service accounts or creating new ones in Google Cloud Console, validate the credentials are properly configured and have the Chat App IAM role assigned.

Response

Success Response (200 OK):

{
  "id": "googlechat_xyz789"
}

json

Error Response (409 Conflict - Invalid JSON):

{
  "error": "conflict",
  "message": "The service account key is not valid JSON. Please provide a valid Google service account JSON key."
}

json

Error Response (409 Conflict - Missing Fields):

{
  "error": "conflict",
  "message": "The service account key is missing required fields (client_email or private_key)."
}

json

Error Response (409 Conflict - Token Exchange Failed):

{
  "error": "conflict",
  "message": "Failed to validate service account credentials. Please check that the service account key is correct and the Chat API is enabled for your project."
}

json

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.

Missing Required Fields: Service account keys downloaded from Google Cloud Console contain all required fields. Keys manually constructed or partially copied may be missing client_email or private_key.

Token Exchange Failure: Ensure the Google Cloud project has the Chat API enabled and the service account has been granted the Chat App role (roles/chat.owner or custom role with chat.messages.create permission). 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.

POST /api/v1/integration/googlechat/{googlechatIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Bot Name",
  "botId": "bot_xyz789",
  "contactCollection": true,
  "sessionDuration": 3600000
}

http

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 JWT audience verification in incoming webhook requests
  • contactCollection (boolean): Enable or disable contact data collection
  • sessionDuration (number or null): Session timeout in milliseconds. Set to null for unlimited sessions. Maximum is one month.
  • autoRespond (string or null): Configure the auto-respond behavior
  • 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 triggers a setup validation event (type: "setup") for the integration. This ensures that any 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:

POST /api/v1/integration/googlechat/{googlechatIntegrationId}/update
Content-Type: application/json

{
  "serviceAccountKey": "{\"type\":\"service_account\",\"project_id\":\"...\"}",
  "projectNumber": "123456789012"
}

http

The response returns the integration ID on success:

{ "id": "googlechat_abc123" }

json

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.

GET /api/v1/integration/googlechat/list

http

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.

GET /api/v1/integration/googlechat/list?take=10&order=asc

http

Filtering by Metadata

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

GET /api/v1/integration/googlechat/list?meta[environment]=production

http

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 visitor contact data is collected during conversations
  • sessionDuration: Conversation session timeout in milliseconds
  • 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

{
  "items": [
    {
      "id": "googlechat_abc123",
      "name": "Support Space Bot",
      "description": "Handles support requests in Google Chat",
      "botId": "bot_xyz789",
      "projectNumber": "123456789012",
      "serviceAccountKey": "********",
      "contactCollection": true,
      "sessionDuration": 1800000,
      "autoRespond": null,
      "allowFrom": null,
      "meta": {},
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "cursor": null
}

json

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.

GET /api/v1/integration/googlechat/{googlechatIntegrationId}/fetch

http

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 visitor contact data is collected during conversations
  • sessionDuration: Conversation session timeout in milliseconds (null for unlimited)
  • 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

{
  "id": "googlechat_abc123",
  "name": "Support Space Bot",
  "description": "Handles support requests in Google Chat spaces",
  "blueprintId": null,
  "botId": "bot_xyz789",
  "serviceAccountKey": "********",
  "projectNumber": "123456789012",
  "contactCollection": true,
  "sessionDuration": 1800000,
  "autoRespond": null,
  "allowFrom": null,
  "meta": { "environment": "production" },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:45:00Z"
}

json

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.

POST /api/v1/integration/googlechat/{googlechatIntegrationId}/delete
Content-Type: application/json

{}

http

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:

{ "id": "googlechat_abc123" }

json

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

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.

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.

Go to cbk.ai