/add-gchat

name: add-gchat
description: Add Google Chat channel integration via Chat SDK.

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](https://console.cloud.google.com) > 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.
NanoClaw's webhook server listens on 127.0.0.1 only, so a tunnel or proxy on this machine works as is. If yours runs on another machine or in Docker on Linux, add `WEBHOOK_HOST=0.0.0.0` to `.env`; it takes effect at the next restart.

Store both in `.env` (set-if-absent). The URL must match