Do I need a public URL for a Google Chat bot?

Not with the Pub/Sub route, where the agent pulls events from a subscription. The webhook route does require a public HTTPS endpoint that Google can post to.

Why does my Google Chat bot receive no messages?

The most common cause is a missing IAM binding — the Chat service must be allowed to publish to your Pub/Sub topic, and your service account must be allowed to subscribe.

Can the Google Chat bot send files?

On the service-account route, outbound file upload is not available because Google Chat requires user authentication for uploads. Text messaging works normally.

← Home

Guide

Connect Google Chat to Your AI Agent

If your team lives in Google Workspace, this puts the agent where the work already happens. There are two ways in, and one of them avoids exposing your bot to the internet entirely.

Pick Your Route First

Google Chat can deliver messages to your bot in two ways, and the choice matters more than anything else on this page.

Pub/Sub. Google publishes events to a topic, and your agent pulls them. Nothing needs to be publicly reachable. This is the Hermes route and it is the better fit for a hosted bot.
Webhook. Google posts events to a public HTTPS URL you provide. This is the OpenClaw route, and it means your instance needs a reachable endpoint.

A second advantage of Pub/Sub: because messages sit in a subscription, a short restart does not lose them. Set the topic retention to seven days and a backlog survives while your agent is down.

Set Up Google Cloud

These steps are the same whichever route you take.

Create or choose a Google Cloud project.
Enable the Google Chat API and the Pub/Sub API on it.
Create a service account. This is the identity your agent uses to send messages, and you will download its JSON key.
Create a Pub/Sub topic and a subscription on it, with message retention set to seven days.
Add the IAM bindings. This is the step people miss: the Chat service needs permission to publish to your topic, and your service account needs permission to subscribe. If either binding is absent, everything looks configured and no message ever arrives.

Configure the Chat App

In the Chat API configuration for your project, set the app name, avatar and description, choose the Pub/Sub connection and point it at your topic, then enable the app for direct messages and spaces as you need. Finally, install the app into a test space so you have somewhere safe to try it.

Hermes Setup

Run the guided setup and pick Google Chat:

hermes gateway setup

Or set it directly:

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=/opt/data/google-chat-sa.json

Upload the service account JSON to your instance rather than pasting its contents anywhere — it is a credential. The subscription name is the full path, not just the short name.

OpenClaw Setup

Install the plugin:

openclaw plugins install @openclaw/googlechat

Then add the channel:

openclaw channels add --channel googlechat

This route needs a public URL for Google to post to. A tunnel such as Cloudflare Tunnel or Tailscale Funnel, or a reverse proxy on a domain you control, all work. Approve your first sender when the pairing code appears:

openclaw pairing approve googlechat <code>

One limitation to know about: because the app authenticates as a service account rather than as a user, outbound file upload is not available on this route. Text works normally.

Troubleshooting

Everything is configured and no messages arrive. Nine times out of ten this is a missing IAM binding on the topic or the subscription.
The bot answers in direct messages but not in a space. The app has not been installed into that space, or it needs to be mentioned there.
Authentication errors. Check the service account JSON path is correct on the instance and that the file is readable.
Messages arrive late in bursts after a restart. That is the Pub/Sub backlog draining, which is the feature working as intended.

Need a Hand?

The Google Cloud side has a lot of steps. Contact support from your dashboard and we will help you get the agent side configured once your project is ready.