Google Chat

What You Get

Direct messages and space mentions
Cards v2 rich responses (buttons, sections, decorated text)
Works in Google Workspace tenants (not consumer Gmail)
Inherits Workspace authentication and admin controls

1. Create a Google Cloud project

Go to the Google Cloud Console
Create a new project (or select an existing one)
Enable the Google Chat API:
- APIs & Services → Library → search for “Google Chat API” → Enable

2. Create a service account

IAM & Admin → Service Accounts → Create Service Account
Name: aibutler-chat (or any label)
Skip the optional role grants
After creation, click the account → Keys → Add Key → JSON
Save the downloaded key file securely

3. Configure the Chat bot

In the Cloud Console, go to Google Chat API → Configuration
Fill in:
- Application name: AI Butler
- Avatar URL: optional icon
- Description: one-line bot description
- Functionality: check both Receive 1:1 messages and Join spaces and group conversations
- Connection settings → App URL: https://your-host/webhook/googlechat
Under Permissions, choose who can install the bot (your whole domain, a specific OU, or individuals)
Save

4. Store Credentials

# Store the service account JSON in the vault
aibutler vault set googlechat_service_account_json "$(cat path/to/key.json)"

5. Enable the Channel

configurations:
  channels:
    active:
      - googlechat

6. Install and Restart

aibutler run

Then add the bot to a Google Chat space from the Workspace admin console or the + New chat menu in Google Chat.

Features

Feature	Supported
1:1 DMs	Yes
Group spaces	Yes (@mentions required)
Cards v2 rich replies	Yes
File attachments	Yes (download only)
Voice messages	No
Streaming replies	No (Google Chat is edit-based)
SSO	Inherited from Workspace

Troubleshooting

Bot doesn’t appear in the spaces menu. Your Workspace admin may need to approve the bot in the admin console (Apps → Google Workspace Marketplace apps).

HTTP 401 Unauthorized. The service account JSON is wrong or expired. Regenerate the key and re-store it in the vault.

Messages received but no reply. Google Chat requires the bot’s app URL to respond within 30 seconds. If your model is slow, consider switching to a faster model for Google Chat or enable response streaming (v0.2).