Google Chat

The Google Chat adapter registers a Snippbot app in Google Workspace so agents can participate in spaces and direct messages using a service account for authentication.

Prerequisites

• A Google Workspace account (paid or trial)
• Google Cloud project with billing enabled
• Admin access to Google Cloud Console and Google Workspace Admin Console
• A publicly accessible Snippbot URL with HTTPS

Setup

1. Create a Google Cloud Project

   Go to console.cloud.google.com → New Project.

2. Enable the Google Chat API

   In your project → APIs & Services → Library → search for Google Chat API → Enable.

3. Create a Service Account

   In IAM & Admin → Service Accounts → Create Service Account:

   • Name: snippbot-chat
   • Role: no project role needed (Chat manages its own permissions)

   After creation, go to the service account → Keys → Add Key → JSON.

   Download the JSON key file — this is your service_account_json.

4. Configure the Chat API

   In APIs & Services → Google Chat API → Configuration:

   • App name: Snippbot
   • Avatar URL: your logo URL
   • Description: your description
   • Functionality: enable Receive 1:1 messages and Join spaces and group conversations
   • Connection settings: HTTP endpoint URL → https://your-snippbot-url.com/webhook/google_chat
   • Slash commands: add /snippbot if desired
   • Click Save

5. Store credentials in Snippbot

   Go to Settings → Channels → Google Chat and paste the entire contents of the JSON key file, or provide a path:

   Via CLI:

   snippbot channel set google_chat \
     --service-account-json "$(cat /path/to/service-account.json)"

6. Start the adapter

   snippbot channel start google_chat

7. Create a channel binding

   In Settings → Channels → Google Chat → Bindings, click Add Binding:

   • Channel ID: the Google Chat space name (e.g., spaces/AABBcc...)
   • Agent: which agent responds
   • Access mode: open / allowlist / admin_only

8. Add the app to a space

   In Google Chat, open the space → Apps → Add apps → search for your app name → Add.

How it works

The Google Chat adapter uses service account authentication:

1. Google Chat delivers webhook events to your endpoint as HTTPS POST with a Bearer token in the Authorization header
2. The adapter verifies the Bearer token to authenticate the request
3. The message is normalized and routed to the bound agent
4. The response is sent back via the Google Chat REST API, authenticated with the service account credentials

Note

Unlike other platforms, Google Chat uses service accounts (not bot tokens). The service account’s private key is used to sign outbound API requests — never expose the JSON key file publicly.

Message types

• Text messages in spaces and DMs
• @mentions in spaces (Snippbot responds when mentioned)
• Cards for rich responses (formatted results, tables, buttons)

Slash commands

Register custom slash commands in the Chat API configuration:

Command	Description
/snippbot	Send a message to the bound agent
/status	Check agent and project status
/help	Show available commands

Access modes

Mode	Who can use the bot
open	Any workspace user in bound spaces
allowlist	Only approved Google accounts (by email)
admin_only	Only admin users

Troubleshooting

Webhook endpoint not accepted by Google Chat

The adapter must be running before configuring the endpoint:

snippbot channel status google_chat

Google Chat sends a verification event to the endpoint on save. Check adapter logs for the verification request.

JWT verification failing

1. Ensure the service account JSON is complete and unmodified
2. Check that the Chat API is enabled in your Google Cloud project
3. Verify the project ID in the JSON matches the project where Chat API is enabled

App not appearing in space search

The Google Workspace admin must publish the app. Go to Google Workspace Admin Console → Apps → Google Workspace Marketplace SDK (or direct publishing for internal apps).

# Check adapter status and last error
snippbot channel logs google_chat

Service account key rotation

When rotating the service account key:

1. Create a new key in Google Cloud Console
2. Update Snippbot: snippbot channel set google_chat --service-account-json "$(cat new-key.json)"
3. Restart the adapter: snippbot channel restart google_chat
4. Delete the old key in Google Cloud Console