Hermes Agent
Hermes Agent Google Chat: Pub/Sub setup and fixes
Updated 22 November 2026
Hermes Agent can run as a bot in Google Chat. It listens for events on a Google Cloud Pub/Sub subscription and answers through the Chat API, so you set up a Cloud project, a topic, a service account and a Chat app before you touch Hermes. This page walks the whole task in order, then covers file attachments, who is allowed to talk to the bot, and the failures the documentation lists.
Facts come from the Google Chat page of the Hermes Agent 0.23.3 documentation, the messaging overview, the environment variable reference and the security guide, all read on 22 November 2026. This guide covers using Google Chat to exchange messages with Hermes.
How the Google Chat connection works
The documentation describes inbound events arriving over a Cloud Pub/Sub pull subscription and outbound messages going out through the Chat REST API. Your Hermes process does not need a public URL, a tunnel or a TLS certificate: it connects, authenticates and listens on the subscription, in the same way a Telegram bot listens with its token. That is why the setup below has no web server step.
| Part | What the docs list |
|---|---|
| Libraries | google-cloud-pubsub, google-api-python-client, google-auth |
| Inbound | Pub/Sub pull subscription |
| Outbound | Chat REST API at chat.googleapis.com |
| Authentication | Service account JSON with roles/pubsub.subscriber and roles/pubsub.viewer on the subscription |
| Who is who | Chat resource names (users/{id}) and email |
One edition note from the docs: Google Chat is part of Google Workspace. You can use this with a personal Workspace on a domain registered through Google, or a work Workspace where you have the admin rights to publish an app. Gmail-only accounts cannot host Chat apps.
The docs also say you can run hermes gateway setup and pick Google Chat for a guided walk-through. If you have not installed Hermes yet, start with how to install Hermes Agent.
Set up Google Cloud: project, APIs and service account
1. Create or pick a project. You need a Google Cloud project to host the Pub/Sub topic. Create one at console.cloud.google.com if you do not have one. The docs say personal accounts get a free tier that easily covers bot traffic. Note the project ID (their example is my-chat-bot-123); you use it in every later step.
2. Enable two APIs. Under APIs & Services, Library, enable the Google Chat API and the Cloud Pub/Sub API. The docs say both are free for the volumes a personal bot generates.
3. Create a service account. Under IAM & Admin, Service Accounts, choose Create Service Account.
- Name it
hermes-chat-bot. - Skip the step that grants the account access to the project. Access on the specific subscription is all you need, and the docs say not to grant project-level Pub/Sub roles.
- Open the account, go to Keys, Add Key, Create new key, JSON and download the file. Save it as
~/.hermes/google-chat-sa.jsonunder the account that runs Hermes, and set the file’s permissions to600so only its owner can read or write it.
The docs add a warning: there is no “Chat Bot Caller” role. Searching for a Chat-specific IAM role and granting it at project level is a mistake they call out, because a Chat bot’s authority comes from being installed in a space, not from IAM. On the subscription you create next, grant the service account both Pub/Sub Subscriber and Pub/Sub Viewer. Hermes uses Viewer to check the subscription at startup.
Create the topic, the permissions and the Chat app
4. Topic and subscription. Under Pub/Sub, Topics, Create topic, use the topic ID hermes-chat-events and leave the other defaults. Then, on the topic’s Subscriptions tab, create a subscription with the ID hermes-chat-events-sub, delivery type Pull, and message retention of 7 days so a backlog survives a Hermes restart. Leave the rest as default.
5. Let Google Chat publish to the topic. On the topic, not the subscription, add the principal chat-api-push@system.gserviceaccount.com with the role Pub/Sub Publisher. The docs mark this critical: without it Google Chat cannot publish events to your topic and the bot never receives anything.
6. Let your service account read the subscription. On the subscription, add your service account by its email address, hermes-chat-bot@<your-project>.iam.gserviceaccount.com, and grant it Pub/Sub Subscriber. Here and in the topic name in step 7, replace <your-project> with the project ID you noted in step 1. Also grant Pub/Sub Viewer on the same subscription, because Hermes calls subscription.get() at startup as a reachability check.
7. Configure the Chat app. Go to APIs & Services, Google Chat API, Configuration and set:
- An app name that users will see (the docs say “Hermes” is reasonable).
- An avatar URL (any public PNG) and a short description for the app directory.
- Functionality: enable Receive 1:1 messages and Join spaces and group conversations.
- Connection settings: select Cloud Pub/Sub and enter the topic name
projects/<your-project>/topics/hermes-chat-events. - Visibility: restrict it to your workspace or specific users, and do not publish to everyone while you are testing.
Save the configuration.
8. Install the bot in a test space. If your workspace has a data-residency or AI-governance policy, get approval before installing the app, including for this test. Then open Google Chat in a browser and start a direct message (DM) with the app by searching for its name in the + New Chat menu. The first time you message it, Google sends an ADDED_TO_SPACE event, which Hermes uses to cache the bot’s own users/{id} so it can ignore its own messages.
Configure Hermes and start the gateway
9. Add these settings to ~/.hermes/.env. In the first two lines, replace my-chat-bot-123 with your project ID and use the subscription you created. In the third, enter the full path to your downloaded service account JSON. In the fourth, enter the email addresses of the people you want to allow, separated by commas:
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
GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.comGOOGLE_CHAT_ALLOWED_USERS is the authorisation list, covered in the next section. The project ID also falls back to GOOGLE_CLOUD_PROJECT, and the service account path falls back to GOOGLE_APPLICATION_CREDENTIALS. The environment variable reference says the service account setting can hold the path or the JSON inline, and that the older name GOOGLE_CHAT_SUBSCRIPTION still works as an alias for the subscription path.
These three optional settings control scheduled delivery and how much data Hermes processes at once.
| Variable | What it does |
|---|---|
GOOGLE_CHAT_HOME_CHANNEL | Default delivery space for cron jobs, written like spaces/AAAA... |
GOOGLE_CHAT_MAX_MESSAGES | Maximum number of Pub/Sub messages Hermes can process at once; the default is 1, so commands in a session run one at a time |
GOOGLE_CHAT_MAX_BYTES | Cap on in-flight message bytes; the default is 16777216 (16 MiB) |
If you use the published Docker image, the Google Chat dependencies are already installed. Docker and hosted images have a read-only Python environment with on-demand installs disabled (HERMES_DISABLE_LAZY_INSTALLS=1). See Hermes Agent in Docker for that setup. On a self-managed installation with a writable environment, install the dependencies with the maintained installer:
python -m plugins.platforms.google_chat.oauth --install-depsIf the gateway is already running, restart it so it loads the dependencies and settings. If it is stopped, start it:
hermes gatewayYou should see a log line beginning [GoogleChat] Connected, followed by the project, the subscription (redacted), the bot’s users/ ID and the flow-control values. Send a message in the test DM. The bot posts a working marker, “Hermes is thinking…”, then edits that same message in place with the real answer, so there are no “message deleted” tombstones.
The marker text is set with typing_status_text in ~/.hermes/config.yaml. Unlike Slack’s ephemeral status line it is a real posted message, so whatever you set briefly appears in the chat. Set typing_indicator: false to turn the marker off.
platforms:
google_chat:
typing_status_text: "is pouncing… 🐾"If you run several profiles under one gateway, each profile reads its own GOOGLE_CHAT_* settings from its own .env and never inherits another profile’s project, subscription or service account. If this profile has no service account configured and the process environment contains credentials for another profile, Hermes logs an error and refuses to use Application Default Credentials. Set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON in this profile’s .env. See Hermes Agent profiles.
Allowed users, DMs and spaces
Who may talk to it. The security guide says that by default the gateway denies every user who is not in an allowlist or paired through a DM. For Google Chat the allowlist is GOOGLE_CHAT_ALLOWED_USERS, a comma-separated list of email addresses. A cross-platform GATEWAY_ALLOWED_USERS also exists. With allow-all settings off, a user needs an allowlist entry or an approved DM pairing to use the bot. If no allowlist is configured, the gateway warns at startup that it will deny unauthorized users.
The variable reference also lists GOOGLE_CHAT_ALLOW_ALL_USERS, which lets any Google Chat user trigger the bot and is marked dev only. The security guide says a bot with terminal access should not be opened to everyone, so keep the allowlist.
DMs and spaces. The Chat app you configured accepts 1:1 messages and can join spaces and group conversations. When a user replies inside a thread, Hermes reads the thread name and posts its reply in the same thread, and each thread gets a separate Hermes session. For cron jobs, GOOGLE_CHAT_HOME_CHANNEL names the space that results go to by default.
Two more variables from the reference help in odd cases: GOOGLE_CHAT_BOOTSTRAP_SPACES takes a comma-separated list of extra space IDs to probe at startup when Hermes works out the bot’s own user ID, and GOOGLE_CHAT_DEBUG_RAW logs redacted Pub/Sub envelopes at DEBUG level, for debugging only.
What the channel can show. Google Chat renders a limited subset of markdown: bold, italic, strikethrough and inline code, plus inline images by URL. Headings and lists are not supported. The agent’s system prompt carries a Google Chat hint so it avoids formatting that will not render. Messages are limited to 4000 characters, and longer replies are split across several messages. The messaging overview lists Google Chat with image, file, thread and typing support, and no voice, reactions or streaming.
When the agent asks a multiple-choice clarifying question, the adapter shows it as a native Card v2 with one button per choice plus an “Other / type answer” button. If the card fails to send, or the question has no fixed choices, it falls back to a plain text question. No configuration is needed.
Send files as real attachments
This step is optional. Without it the bot can post text, inline images by URL and download cards for audio, video and documents. To deliver native Chat attachments, each user authorises the bot once. The reason, per the docs: Google Chat’s media.upload endpoint rejects service account authentication, and no IAM role or scope fixes that, so the bot has to upload as the user who asked for the file.
One-time setup, per profile. In the same Cloud project open APIs & Services, Credentials, choose Create credentials, OAuth client ID, Desktop app, download the JSON and move it to the machine that runs Hermes. Then register it:
python -m plugins.platforms.google_chat.oauth --client-secret /path/to/client_secret.jsonFor a named profile, replace <profile> with the profile used by the gateway and run hermes -p <profile> python -m plugins.platforms.google_chat.oauth --client-secret /path/to/client_secret.json. The client secret is stored in that profile’s Hermes home and is not shared across profiles, so register it once for each profile that needs attachments.
Per-user authorisation. Each user does this once, in their own DM with the bot:
- Send
/setup-files. The bot replies with status and the next step. - Send
/setup-files start. The bot replies with an OAuth URL. - Open the URL and click Allow. The browser then fails to load a
http://localhost:1/address; the docs say that failure is expected, because the code is in the address bar. - Copy the failed URL, or just the
code=value, and send it back as/setup-files <PASTED_URL>. The bot exchanges it for a refresh token.
The token is saved under ~/.hermes/google_chat_user_tokens/, one file per user. Later file requests in that user’s DM use their token. /setup-files revoke deletes only that user’s token. The flow asks for one scope, chat.messages.create, which the docs say covers the upload and the message that references it, and nothing from Drive.
If the person asking has no token, the bot falls back to a legacy single-user token at ~/.hermes/google_chat_user_token.json if one exists from an older install. If neither exists, it posts a text notice telling the asker to run /setup-files.
Troubleshooting
The bot stays silent after you send a message. Work through the docs’ three checks:
- Look in the Cloud console for undelivered messages on the subscription. If there are some, Hermes is not authenticated: check
GOOGLE_CHAT_SERVICE_ACCOUNT_JSONand that the service account is a Pub/Sub Subscriber on the subscription. - If the subscription has zero messages, Google Chat is not publishing. Recheck the binding on the topic:
chat-api-push@system.gserviceaccount.comneeds Pub/Sub Publisher. - Read the
hermes gatewaylogs for[GoogleChat] Connected. If you see[GoogleChat] Config validation failed, the message names the environment variable to fix.
An error appears instead of the agent’s answer. Look for [GoogleChat] Pub/Sub stream died in the logs. If it repeats, the service account 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. Install it in the space again; the next ADDED_TO_SPACE event re-enables messaging automatically.
Many “Rate limit hit” warnings. The docs say the Chat API default quota allows 60 messages per space per minute. If replies exceed that rate, Hermes waits progressively longer between retries, so users may see a delay. Consider shorter replies or raising the quota in the Cloud console.
The bot keeps posting the /setup-files notice instead of files. The asker has no per-user token and there is no legacy fallback. Have them run /setup-files in their DM and follow the steps above; the next file request uploads natively without a gateway restart.
/setup-files start says no client credentials are stored. The one-time registration was not done for this profile. Run the registration command under the profile the gateway uses, then send /setup-files start again.
/setup-files <PASTED_URL> says the token exchange failed. The auth code is single-use and short-lived, typically a few minutes. Send /setup-files start for a fresh URL and try again.
Security notes
- Keep the roles narrow. The adapter requests the
chat.botandpubsubscopes, and the docs say IAM should be the real enforcement: grant the service accountroles/pubsub.subscriberandroles/pubsub.vieweron the subscription, not project-level or organisation-level Pub/Sub roles. - Download protection. Hermes only attaches the service account’s bearer token to URLs on a short allowlist of Google-owned hosts. Any other host is rejected before the request, which the docs say guards against a crafted event redirecting the token to the cloud metadata service.
- Redaction. Service account emails, subscription paths and topic paths are stripped from logs, including the
GOOGLE_CHAT_DEBUG_RAW=1dump. - Token files are plain JSON. The per-user tokens and the service account key are protected by filesystem permissions only, so keep them private.
- Compliance. If the workspace is regulated, for example by a data-residency or AI-governance policy, the docs say to get approval before the first install, and a test installation counts.
Google Chat on ReadyHermes
Google Chat is not in the ReadyHermes Channels panel. We have not tested connecting it to a ReadyHermes assistant, and we do not support that setup. The panel offers Telegram, WhatsApp, Discord, WeChat and Lark, plus the Hermes Desktop connection. If one of those suits you, see Hermes Agent on Telegram, on WhatsApp, on Discord or on WeChat.
If Google Chat is the channel you need, run Hermes yourself with the steps above. ReadyHermes plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. Self-hosting vs managed hosting helps you decide.
Questions
Does Hermes Agent need a public URL for Google Chat?
No. The documentation says the Google Chat integration uses a Cloud Pub/Sub pull subscription for inbound events and the Chat REST API for outbound messages, so your Hermes process does not need a public URL, a tunnel or a TLS certificate. It connects, authenticates and listens on the subscription.
Which Google accounts can host the bot?
Google Chat is part of Google Workspace. The docs say you can use it with a personal Workspace on a domain registered through Google, or a work Workspace where you have the admin rights to publish an app. Gmail-only accounts cannot host Chat apps.
Which IAM roles does the bot need?
On the topic, chat-api-push@system.gserviceaccount.com needs Pub/Sub Publisher. On the subscription, your service account needs Pub/Sub Subscriber and Pub/Sub Viewer. The docs say there is no IAM role called Chat Bot Caller, and they warn against project-level Pub/Sub roles.
How do I control who can use the Google Chat bot?
Set GOOGLE_CHAT_ALLOWED_USERS in ~/.hermes/.env to a comma-separated list of email addresses. By default the gateway denies users who are not in an allowlist or paired via DM. GOOGLE_CHAT_ALLOW_ALL_USERS exists but is marked dev only.
Can I use Google Chat with a ReadyHermes assistant?
Google Chat is not in the ReadyHermes Channels panel. We have not tested connecting it to a ReadyHermes assistant, and we do not support that setup. The panel offers Telegram, WhatsApp, Discord, WeChat and Lark, plus the Hermes Desktop connection.