Add Google Chat Channel

Adds Google Chat support via the Chat SDK bridge. NanoClaw doesn't ship channels in trunk — this skill copies the Google Chat adapter in from the channels branch.

The mechanical steps under Apply carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Apply

1. Copy the adapter and its registration test

Fetch the channels branch and copy the Google Chat adapter and its registration test into src/channels/ (overwrite — the branch is canonical):

src/channels/gchat.ts
src/channels/gchat-registration.test.ts

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './gchat.js';

3. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and latest:

@chat-adapter/gchat@4.41.1

4. Build and validate

Build first: it guards the typed createChatSdkBridge(...) core call and proves the dependency is installed. Then run the one integration test.

pnpm run build

pnpm exec vitest run src/channels/gchat-registration.test.ts

gchat-registration.test.ts imports the real channel barrel and asserts the registry contains gchat. It goes red if the import line is deleted or drifts, if the barrel fails to evaluate, or if @chat-adapter/gchat isn't installed (the import throws) — so it also covers the dependency from step 3. End-to-end delivery against a real Google Chat space is verified manually once the service runs — see Credentials and Next Steps.

Credentials

Google Cloud setup is human and interactive — these steps are prose, not directives (no parser can click through the Google Cloud Console). A recipe rebuild produces a compiling, registered adapter that cannot receive a message until they're done.

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Google Chat API
4. Go to Google Chat API > Configuration (one page, then Save):
   • Make sure Build this Chat app as a Google Workspace add-on is checked
   • Fill in App name (up to 25 alphanumeric characters), Avatar URL (an HTTPS link to a square PNG or JPEG) and Description (max 40 characters)
   • Turn on Enable interactive features; to use the app in spaces, also check Join spaces and group conversations
   • Connection settings: select HTTP endpoint URL, then under Triggers select Use a common HTTP endpoint URL for all triggers and set it to https://your-domain/webhook/gchat
   • Visibility: check Make this chat app available to specific people and groups in your domain and add up to five people, or Google Groups, who will chat with it. Only accounts in the project's own Workspace can find the app
5. Create a Service Account:
   • Go to IAM & Admin > Service Accounts > Create service account. It needs no roles, so skip the permissions and principals steps
   • Open it, then Keys > Add key > Create new key > JSON. The key file downloads

Store the credentials

Capture the service account JSON, then write it. prompt only asks and binds the answer to a name; a separate directive consumes it — so the same prompt could feed ncl or the OneCLI vault instead of .env by swapping only the consumer. Here it goes to .env (set-if-absent — a value you've already filled in is never overwritten) as a single-line string:

Paste the service account JSON as a single line — the key file you downloaded, e.g. `{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}`.

GCHAT_CREDENTIALS={{gchat_credentials}}

Webhook server

The Chat SDK bridge automatically starts a shared webhook server on port 3000 (WEBHOOK_PORT to change it), handling /webhook/gchat. This port must be publicly reachable for Google Chat to deliver events — it's the HTTP endpoint URL you set in the Connection settings above. Running locally, expose it with ngrok (ngrok http 3000), a Cloudflare Tunnel, or a reverse proxy on a VPS.

Webhook verification

Google signs every webhook, and Google Chat won't start until NanoClaw can check the signature. The adapter reads only Workspace add-on events, and an add-on signs each webhook for its HTTP endpoint URL with a service account named after your project number. So it needs both values. Tell the user:

In Google Cloud Console, open Google Chat API → Configuration. Make sure "Build this Chat app as a Google Workspace add-on" is checked, and that under Connection settings → Triggers, "Use a common HTTP endpoint URL for all triggers" is selected with a URL ending in /webhook/gchat. Save.
An existing Chat app that is not an add-on has no such checkbox: it needs Google's "Convert to add-on" steps first (https://developers.google.com/workspace/chat/convert), and that conversion can't be undone.
Then find the project number: the same page shows a Service Account Email like service-123456789012@gcp-sa-gsuiteaddons.iam.gserviceaccount.com, and the digits in it are your project number.

Store both in .env (set-if-absent). The URL must match the console exactly, or every webhook is rejected. Re-running this skill keeps a value already in .env, so when the URL changes (a new tunnel), edit GOOGLE_CHAT_ENDPOINT_URL there yourself and restart:

Paste the HTTP endpoint URL from the Chat app configuration, e.g. `https://chat.example.com/webhook/gchat`. A URL already in `.env` is kept, so after a URL change edit `GOOGLE_CHAT_ENDPOINT_URL` in `.env` and restart.

GOOGLE_CHAT_ENDPOINT_URL={{gchat_endpoint_url}}

Paste your Google Cloud project number, digits only, e.g. `123456789012`.

GOOGLE_CHAT_PROJECT_NUMBER={{gchat_project_number}}

Bot user id (for @mentions in spaces)

DMs work without it, but in a space an @mention only counts when NanoClaw knows the app's own user id. It is easiest to find once the app has replied to you, so on a first install answer later and add it then. Tell the user:

To find the bot user id: DM the app and let it reply. Open https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/list, use "Try this method" with parent set to the DM space (spaces/<id>, the last part of the chat URL) and orderBy set to createTime DESC, and copy sender.name from a message whose sender type is BOT. It looks like users/123456789.
Without it, DMs still work; add GOOGLE_CHAT_BOT_USER_ID to .env later and restart.

Do you have the bot user id now? `now` to paste it, `later` to add it to `.env` after the app has replied.

Paste the bot user id, e.g. `users/123456789`.

GOOGLE_CHAT_BOT_USER_ID={{gchat_bot_user_id}}

Next Steps

If you're in the middle of /setup, return to the setup flow now. Otherwise run /manage-channels to wire this channel to an agent group.

Channel Info

• type: gchat
• terminology: Google Chat has "spaces." A space can be a group conversation or a direct message with the bot.
• how-to-find-id: Open the space in Google Chat, look at the URL — the space ID is the segment after /space/ (e.g. spaces/AAAA...). Or use the Google Chat API to list spaces.
• supports-threads: yes
• typical-use: Interactive chat — team spaces or direct messages
• default-isolation: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive contexts.

Troubleshooting

Google Chat won't start: "GCHAT_CREDENTIALS in .env must be the service account JSON key on one line". GCHAT_CREDENTIALS must be the entire service account JSON collapsed to one line, with its client_email and RSA private_key. A truncated paste (shells often mangle the multi-line private key) is the usual cause; download a fresh JSON key under IAM & Admin → Service Accounts → Keys and re-paste it as a single line.

Google Cloud won't create the JSON key. Organizations created on or after May 3, 2024 enforce constraints/iam.managed.disableServiceAccountKeyCreation by default. An organization policy admin can turn off the constraint the error names (that one, or the older constraints/iam.disableServiceAccountKeyCreation) for this project only, under IAM & Admin → Organization Policies.

Google Chat won't start: "needs GOOGLE_CHAT_ENDPOINT_URL and GOOGLE_CHAT_PROJECT_NUMBER". One of them is missing from .env, or the number has something other than digits. Add both as described under Webhook verification and restart. "must be an https URL" means GOOGLE_CHAT_ENDPOINT_URL isn't a valid https:// address.

Every webhook is rejected (401), with a JWT warning in the log. GOOGLE_CHAT_ENDPOINT_URL must match the trigger URL in Google Chat API → Configuration exactly, and GOOGLE_CHAT_PROJECT_NUMBER must be the number of the project the Chat app belongs to. After a URL change, edit .env by hand: re-running the skill keeps the old value.

DMs work, but @mentions in a space are ignored. GOOGLE_CHAT_BOT_USER_ID is missing (the log shows "Google Chat botUserId is not configured" at startup) or wrong (no warning; mentions just don't match). Find it as described under Bot user id, add it to .env and restart.

Webhooks arrive without errors, but nothing reaches the agent. The app isn't a Workspace add-on, and the adapter ignores the older event format. Convert it with Google's Convert to add-on steps (https://developers.google.com/workspace/chat/convert); the conversion can't be undone.

Messages sent in the space never reach the agent. Google Chat delivers only to the HTTP endpoint URL set under Google Chat API → Configuration, and that URL must be publicly reachable at /webhook/gchat (shared webhook server, port 3000). Tunnel hostnames (ngrok free tier) change on restart — make sure the Configuration URL matches the tunnel that's actually up.

The app doesn't appear when adding it to a space. Check the Chat API Configuration page: the app status must be live and its visibility must include your domain or user, and you must be adding it from the same Google Workspace the Cloud project belongs to.

Everything configured but still silent. Run pnpm exec vitest run src/channels/gchat-registration.test.ts — red means the barrel import or the @chat-adapter/gchat install drifted, so re-run the Apply steps. If green, restart the service so it picks up the adapter and .env, then watch logs/nanoclaw.log for the inbound webhook hit.