hermes-agent/website/docs/user-guide/messaging/google_chat.md

sidebar_position	title	description
12	Google Chat	Set up Hermes Agent as a Google Chat bot using Cloud Pub/Sub

Google Chat Setup

Connect Hermes Agent to Google Chat as a bot. The integration uses Cloud Pub/Sub pull subscriptions for inbound events and the Chat REST API for outbound messages. Equivalent ergonomics to Slack Socket Mode or Telegram long-polling: your Hermes process does not need a public URL, a tunnel, or a TLS certificate. It connects, authenticates, and listens on a subscription — the same way a Telegram bot listens on a token.

:::note Workspace edition Google Chat is part of Google Workspace. You can use this integration with a personal Workspace (@yourdomain.com registered through Google) or a work Workspace where you have the Admin rights to publish an app. Gmail-only accounts cannot host Chat apps. :::

Overview

Component	Value
Libraries	google-cloud-pubsub, google-api-python-client, google-auth
Inbound transport	Cloud Pub/Sub pull subscription (no public endpoint)
Outbound transport	Chat REST API (chat.googleapis.com)
Authentication	Service Account JSON with roles/pubsub.subscriber on the subscription
User identification	Chat resource names (users/{id}) + email

---

Step 1: Create or pick a GCP project

You need a Google Cloud project to host the Pub/Sub topic. If you don't have one, create it at console.cloud.google.com — personal accounts get a free tier that easily covers bot traffic.

Note the project ID (e.g., my-chat-bot-123). You'll use it in every subsequent step.

---

Step 2: Enable two APIs

In the console, go to APIs & Services → Library and enable:

• Google Chat API
• Cloud Pub/Sub API

Both are free for the volumes a personal bot generates.

---

Step 3: Create a Service Account

IAM & Admin → Service Accounts → Create Service Account.

• Name: hermes-chat-bot
• Skip the "Grant this service account access to project" step. IAM on the specific subscription is all you need — do NOT grant project-level Pub/Sub roles.

After creation, open the SA, go to Keys → Add Key → Create new key → JSON and download the file. Save it somewhere only Hermes can read (e.g., ~/.hermes/google-chat-sa.json, chmod 600).

:::caution There is NO "Chat Bot Caller" role A common mistake is to search for a Chat-specific IAM role and grant it at the project level. That role doesn't exist. Chat bot authority comes from being installed in a space, not from IAM. All your SA needs is Pub/Sub subscriber on the subscription you create in the next step. :::

---

Step 4: Create the Pub/Sub topic and subscription

Pub/Sub → Topics → Create topic.

• Topic ID: hermes-chat-events
• Leave the defaults for everything else.

After creation, the topic's detail page has a Subscriptions tab. Create one:

• Subscription ID: hermes-chat-events-sub
• Delivery type: Pull
• Message retention: 7 days (so backlog survives a hermes restart)
• Leave the rest default.

---

Step 5: IAM binding on the topic (critical)

On the topic (not the subscription), add an IAM principal:

• Principal: chat-api-push@system.gserviceaccount.com
• Role: Pub/Sub Publisher

Without this, Google Chat cannot publish events to your topic and your bot will never receive anything.

---

Step 6: IAM binding on the subscription

On the subscription, add your own Service Account as a principal:

• Principal: hermes-chat-bot@<your-project>.iam.gserviceaccount.com
• Role: Pub/Sub Subscriber

Also grant Pub/Sub Viewer on the same subscription — Hermes calls subscription.get() at startup as a reachability check.

---

Step 7: Configure the Chat app

Go to APIs & Services → Google Chat API → Configuration.

• App name: whatever you want users to see ("Hermes" is reasonable).
• Avatar URL: any public PNG (Google has some defaults).
• Description: a short sentence shown in the app directory.
• Functionality: enable Receive 1:1 messages and Join spaces and group conversations.
• Connection settings: select Cloud Pub/Sub, enter the topic name projects/<your-project>/topics/hermes-chat-events.
• Visibility: restrict to your workspace (or specific users) — do not publish to everyone while you're testing.

Save.

---

Step 8: Install the bot in a test space

Open Google Chat in a browser. Start a DM with your app by searching for its name in the + New Chat menu. The first time you message it, Google sends an ADDED_TO_SPACE event that Hermes uses to cache the bot's own users/{id} for self-message filtering.

---

Step 9: Configure Hermes

Add the Google Chat section to ~/.hermes/.env:

# Required
GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json

# Authorization — paste the emails of people allowed to talk to the bot
GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.com

# Optional
GOOGLE_CHAT_HOME_CHANNEL=spaces/AAAA...         # default delivery destination for cron jobs
GOOGLE_CHAT_MAX_MESSAGES=1                      # Pub/Sub FlowControl; 1 serializes commands per session
GOOGLE_CHAT_MAX_BYTES=16777216                  # 16 MiB — cap on in-flight message bytes

The project ID also falls back to GOOGLE_CLOUD_PROJECT, and the SA path falls back to GOOGLE_APPLICATION_CREDENTIALS — use whichever convention you prefer.

Install Hermes with the optional dependencies:

pip install 'hermes-agent[google_chat]'

Start the gateway:

hermes gateway

You should see a log line like:

[GoogleChat] Connected; project=my-chat-bot-123, subscription=<redacted>,
             bot_user_id=users/XXXX, flow_control(msgs=1, bytes=16777216)

Send "hola" in the test DM. The bot posts a "Hermes is thinking…" marker, then edits that same message in place with the real response — no "message deleted" tombstones.

---

Formatting and capabilities

Google Chat renders a limited markdown subset:

Supported	Not supported
*bold*, _italic_, ~strike~, `code`	Headings, lists
Inline images via URL	Interactive Card v2 buttons (v1 of this gateway)
Native file attachments (after /setup-files — see Step 10)	Native voice notes / circular video notes

The agent's system prompt includes a Google Chat–specific hint so it knows these limits and avoids formatting that won't render.

Message size limit: 4000 characters per message. Longer agent responses are automatically split across multiple messages.

Thread support: when a user replies inside a thread, Hermes detects the thread.name and posts its reply in the same thread, so each thread gets a separate Hermes session.

---

Step 10: Native attachment delivery (optional)

Out of the box the bot can post text, inline images via URL, and download cards for audio/video/documents. To deliver native Chat attachments — the same file widget you get when a human drags-and-drops a file — each user authorizes the bot once via a per-user OAuth flow.

Why a separate flow

Google Chat's media.upload endpoint hard-rejects service-account auth:

This method doesn't support app authentication with a service account. Authenticate with a user account.

There's no IAM role or scope that fixes this. The endpoint only accepts user credentials. So the bot has to act as a user whenever it uploads a file — specifically, as the user who asked for the file.

One-time host setup

1. Go to APIs & Services → Credentials in the same GCP project.
2. Create credentials → OAuth client ID → Desktop app.
3. Download the JSON. Move it onto the host that runs Hermes.
4. On the host, register the client with Hermes:

python -m gateway.platforms.google_chat_user_oauth \
    --client-secret /path/to/client_secret.json

That writes ~/.hermes/google_chat_user_client_secret.json. This is shared infrastructure — it identifies the OAuth app, not any individual user. One file per host is enough no matter how many users authorize later.

Per-user authorization (in chat)

Each user runs the flow once, in their own DM with the bot:

1. They send /setup-files to the bot. It replies with status and the next step.
2. They send /setup-files start. The bot replies with an OAuth URL.
3. They open the URL, click Allow, and watch the browser fail to load http://localhost:1/?...&code=.... That failure is expected — the auth code is in the URL bar.
4. They copy the failed URL (or just the code=... value) and paste it back into chat as /setup-files <PASTED_URL>. The bot exchanges it for a refresh token.

The token lands at ~/.hermes/google_chat_user_tokens/<sanitized_email>.json. Subsequent file requests in that user's DM use their token, so the bot uploads as them and the message lands in their space.

To revoke later: /setup-files revoke deletes only that user's token. Other users' tokens are untouched.

Scope

The flow requests exactly one scope: chat.messages.create. That covers both media.upload and the messages.create that references the uploaded attachmentDataRef. No Drive, no broader Chat scopes — this is least-privilege on purpose.

Multi-user behavior

When the asker has no per-user token yet, the bot falls back to a legacy single-user token at ~/.hermes/google_chat_user_token.json (if present from a pre-multi-user install). When neither is available, the bot posts a clear text notice telling the asker to run /setup-files.

A user revoking only clears their own slot. A 401/403 from one user's token evicts only that user's cache. Users don't disrupt each other.

---

Troubleshooting

Bot stays silent after sending "hola."

1. Check the Pub/Sub subscription has undelivered messages in the console. If it does, Hermes isn't authenticated — verify GOOGLE_CHAT_SERVICE_ACCOUNT_JSON and that the SA is listed as Pub/Sub Subscriber on the subscription.
2. If the subscription has zero messages, Google Chat isn't publishing. Double-check the IAM binding on the topic: chat-api-push@system.gserviceaccount.com must have Pub/Sub Publisher.
3. Check hermes gateway logs for [GoogleChat] Connected. If you see [GoogleChat] Config validation failed, the error message tells you which env var to fix.

Bot replies but an error message appears instead of the agent's answer.

Check logs for [GoogleChat] Pub/Sub stream died — if these repeat, your SA credentials may have been rotated or the subscription deleted. After 10 attempts the adapter marks itself fatal.

"403 Forbidden" on every outbound message.

The bot was removed from the space, or you revoked it in the Chat API console. Re-install it in the space (the next ADDED_TO_SPACE event will re-enable messaging automatically).

Too many "Rate limit hit" warnings.

The Chat API's default quotas allow 60 messages per space per minute. If your agent produces long streaming responses that exceed that, the adapter retries with exponential backoff — but you'll still see user-visible latency. Consider concise responses or raising the quota in the GCP console.

Bot keeps posting the "/setup-files" notice instead of files.

The asker has no per-user OAuth token and there's no legacy fallback. Run /setup-files in their DM and follow Step 10. After the exchange completes the next file request uploads natively without a gateway restart.

/setup-files start says "No client credentials stored on the host."

The one-time host setup wasn't done. From a terminal on the host that runs Hermes:

python -m gateway.platforms.google_chat_user_oauth \
    --client-secret /path/to/client_secret.json

Then send /setup-files start again.

/setup-files <PASTED_URL> says "Token exchange failed."

The auth code is single-use and short-lived (typically a few minutes). Send /setup-files start to get a fresh URL and retry.

---

Security notes

• Service Account scope: the adapter requests chat.bot and pubsub scopes. IAM should be the actual enforcement — grant your SA the minimum (roles/pubsub.subscriber + roles/pubsub.viewer on the subscription), not project-level or org-level Pub/Sub roles.
• Attachment download protection: Hermes will only attach the SA bearer token to URLs whose host matches a short allowlist of Google-owned domains (googleapis.com, drive.google.com, lh[3-6].googleusercontent.com, and a few others). Any other host is rejected before the HTTP request, to protect against SSRF scenarios where a crafted event could redirect the bearer token to the GCE metadata service.
• Redaction: Service Account emails, subscription paths, and topic paths are stripped from log output by agent/redact.py. The debug envelope dump (GOOGLE_CHAT_DEBUG_RAW=1) routes through the same redaction filter and logs at DEBUG level.
• Compliance: if you plan to connect this bot to a regulated workspace (anything with a data-residency or AI-governance policy), get that approval before the first install.
• User OAuth scope: the per-user attachment flow requests only chat.messages.create — the minimum that covers media.upload plus the follow-up messages.create. Tokens are persisted as plain JSON at ~/.hermes/google_chat_user_tokens/<sanitized_email>.json (filesystem permissions are the protection — same model as the SA key file). Each token is owned by exactly one user; revoke is scoped to that user.