Google Chat
This document was written by AI and has been manually reviewed.
Google Chat#
The Google Chat driver bridges Google Chat spaces with the rest of your platforms using a service account and the Google Chat REST API. It starts an HTTP server that receives message events pushed by Google, and sends replies via the Chat API.
Prerequisites#
Google Workspace account needed, or you will hit this: 
Create a Google Cloud project at console.cloud.google.com (or use an existing one).
Enable the Google Chat API: go to APIs & Services → Library, search for “Google Chat API”, and enable it.
Create a service account: go to IAM & Admin → Service Accounts, create a new account, and download a JSON key file.
Configure the Chat app: go to APIs & Services → Google Chat API → Configuration and fill in:
App name, Avatar URL, Description (required fields)
Under Connection settings, select HTTP endpoint URL and enter your bot’s public URL, e.g. https://example.com/google-chat/events.
Under Visibility, choose which users or groups can install the bot.
Add the bot to a space: In Google Chat, create or open a space, click Add people & apps, and add your bot by name.
The HTTP endpoint must be publicly reachable over HTTPS. Use a reverse proxy (nginx, Caddy) or a tunnel (ngrok / Cloudflare Tunnel) for development.
Config keys#
Add under googlechat.<instance_id> in config.json:
| service_account_file | Yes* | — | Path to the service account JSON key file |
| service_account_json | Yes* | — | Inline service account JSON string (alternative to file) |
| listen_port | No | 8090 | HTTP port the driver listens on |
| listen_path | No | "/google-chat/events" | HTTP path for the event endpoint |
| endpoint_url | No | — | Full public URL of the endpoint (enables request signature verification) |
| max_file_size | No | 52428800 (50 MB) | Maximum attachment size in bytes |
| proxy | No | — | Proxy URL for all Google Chat API requests (e.g., http://proxy.example.com:8080 or socks5://proxy.example.com:1080). Set to null to explicitly disable proxy for this instance (ignores global proxy setting). |
* Exactly one of service_account_file or service_account_json is required.
Using a file path#
{
"googlechat": {
"my_space": {
"service_account_file": "/secrets/google-chat-sa.json",
"listen_port": 8090,
"endpoint_url": "https://example.com/google-chat/events"
}
}
}Inline JSON (useful with secrets managers)#
{
"googlechat": {
"my_space": {
"service_account_json": "{\"type\":\"service_account\",\"project_id\":\"...\", ...}"
}
}
}Rule channel keys#
| space_name | Google Chat space resource name, e.g. "spaces/AAAA" |
The space_name is present in every received event. You can also find it via the Chat API or by inspecting the name field of a space object in the Google Cloud Console.
{
"my_space": {
"space_name": "spaces/AAAAAbCdEfG"
}
}How it works#
Receive: Google Chat POSTs a JSON event to the configured endpoint whenever a user sends a message to the bot. The driver:
Returns {"text": ""} immediately to acknowledge the event (required by Google)
Ignores non-MESSAGE event types (ADDED_TO_SPACE, REMOVED_FROM_SPACE, etc.)
Skips messages sent by bots (including itself)
Uses argumentText (text after the @mention) when available, falling back to the full text field
Downloads inline attachments using the service-account token and forwards them to the bridge
Send: For each outgoing message the driver:
Obtains (or refreshes) a service-account OAuth2 access token
POSTs a message to https://chat.googleapis.com/v1/{space_name}/messages
For images that have a public HTTPS URL, sends a Card v2 with an image widget
For other attachments (or images without a public URL), sends a text label [Type: filename]
Request verification#
When endpoint_url is set, the driver verifies every incoming request against Google’s signed OIDC token:
Checks the Authorization: Bearer <token> header
Validates the token’s signature against Google’s public keys
Confirms the audience matches endpoint_url
Confirms the sender email is chat@system.gserviceaccount.com
If endpoint_url is omitted, verification is skipped (safe for development or deployments behind a firewall).
Notes#
The service account must have the Chat API enabled in the same project; it does not need any IAM roles.
Google Chat requires a valid HTTPS endpoint. Plain HTTP is rejected by the Chat configuration UI.
Images are sent as Card v2 widgets only when the attachment already has a public URL. Binary attachments from other platforms (e.g., NapCat) appear as text labels since Google Chat’s REST API does not support direct binary uploads without additional Drive/storage setup.
The rich_header prefix uses Google Chat’s limited Markdown syntax: *bold* and _italic_.
Google Chat currently supports spaces, direct messages, and group DMs. Use the space_name from the appropriate conversation.