Merge pull request #1 from iHildy/feat/googlechat-user-oauth
Feat/googlechat user oauth
This commit is contained in:
18 files changed
+986
-42
No files matched your search
@@ -5,9 +5,7 @@ read_when:
|
||||
---
|
||||
# Google Chat (Chat API)
|
||||
|
||||
Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
|
||||
|
||||
## Quick setup (beginner)
|
||||
## Service Account Setup
|
||||
1) Create a Google Cloud project and enable the **Google Chat API**.
|
||||
- Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
|
||||
- Enable the API if it is not already enabled.
|
||||
@@ -46,6 +44,71 @@ Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
|
||||
8) Set the webhook audience type + value (matches your Chat app config).
|
||||
9) Start the gateway. Google Chat will POST to your webhook path.
|
||||
|
||||
## User OAuth (optional, enables reactions)
|
||||
Service account covers almost all features, but **reactions and user-attributed actions require user OAuth**.
|
||||
|
||||
### Option A: Use gog OAuth (recommended if you already use `gog`)
|
||||
If you already use `gog` for Google Workspace, you can reuse its OAuth client + refresh token.
|
||||
`gog` stores the OAuth client credentials JSON in your config directory and the refresh token in your system keyring.
|
||||
|
||||
1) Ensure `gog` is already authorized:
|
||||
```bash
|
||||
gog auth list
|
||||
```
|
||||
2) Configure Google Chat to reuse `gog`:
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
googlechat: {
|
||||
oauthFromGog: true,
|
||||
// Optional when multiple gog clients or accounts are configured:
|
||||
gogAccount: "you@example.com",
|
||||
gogClient: "work"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
3) Ensure `gog` can access its keyring on the gateway host.
|
||||
- `gog` stores refresh tokens in the system keychain by default (not inside `credentials.json`).
|
||||
- For headless systems (systemd, SSH-only), switch to file keyring + password (see `gog` docs).
|
||||
- Set `GOG_KEYRING_BACKEND=file` and `GOG_KEYRING_PASSWORD=...` for the gateway service.
|
||||
- The file keyring lives under your gog config directory (for example `~/.config/gogcli/keyring/`).
|
||||
4) Verify `gog` is visible to clawdbot and ask it to run:
|
||||
```bash
|
||||
Run `gog auth tokens list --json` and tell me if you can access services.
|
||||
```
|
||||
This lists token keys only (no secrets). If this fails, install `gog` on the gateway host and ensure the keyring is accessible.
|
||||
For non-interactive services, set `GOG_KEYRING_PASSWORD` in the gateway environment so `gog` can unlock the keyring.
|
||||
5) Set `typingIndicator` to "reaction" in your clawdbot config.
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
"googlechat": {
|
||||
actions: { reactions: true },
|
||||
typingIndicator: "reaction",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Clawdbot reads `gog` OAuth client files from:
|
||||
- `~/.config/gogcli/credentials.json`
|
||||
- `~/.config/gogcli/credentials-<client>.json`
|
||||
- `~/.config/gogcli/credentials-<domain>.json` (or macOS equivalent)
|
||||
|
||||
Clawdbot queries `gog auth tokens list --json` to discover which account to use, then runs `gog auth tokens export <email> --out <tmp>` to read the refresh token. If you have multiple gog accounts, set `gogAccount` (or `GOG_ACCOUNT`) to pick the right one. If this fails, set `oauthRefreshToken` manually.
|
||||
|
||||
### Option B: Manual OAuth
|
||||
1) Configure OAuth consent + create OAuth client credentials in your Google Cloud project (desktop app recommended).
|
||||
2) Use an OAuth 2.0 flow to request **offline** access and collect a refresh token.
|
||||
- Required scopes for reactions include:
|
||||
- `https://www.googleapis.com/auth/chat.messages.reactions.create`
|
||||
- `https://www.googleapis.com/auth/chat.messages.reactions`
|
||||
- (or) `https://www.googleapis.com/auth/chat.messages`
|
||||
3) Save the client credentials + refresh token in your config or env vars (examples below).
|
||||
|
||||
**Tip:** user OAuth actions are attributed to the user in Google Chat.
|
||||
|
||||
## Add to Google Chat
|
||||
Once the gateway is running and your email is added to the visibility list:
|
||||
1) Go to [Google Chat](https://chat.google.com/).
|
||||
@@ -144,6 +207,17 @@ Use these identifiers for delivery and allowlists:
|
||||
"googlechat": {
|
||||
enabled: true,
|
||||
serviceAccountFile: "/path/to/service-account.json",
|
||||
// Optional: user OAuth for reactions + user-attributed actions
|
||||
oauthClientFile: "/path/to/oauth-client.json",
|
||||
oauthRefreshToken: "1//0g...",
|
||||
// Or reuse gog:
|
||||
// oauthFromGog: true,
|
||||
// gogAccount: "you@example.com",
|
||||
// gogClient: "work",
|
||||
// Or explicit fields:
|
||||
// oauthClientId: "123456.apps.googleusercontent.com",
|
||||
// oauthClientSecret: "GOCSPX-...",
|
||||
// oauthRedirectUri: "https://your.host/googlechat/oauth/callback",
|
||||
audienceType: "app-url",
|
||||
audience: "https://gateway.example.com/googlechat",
|
||||
webhookPath: "/googlechat",
|
||||
@@ -171,6 +245,11 @@ Use these identifiers for delivery and allowlists:
|
||||
|
||||
Notes:
|
||||
- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
|
||||
- User OAuth can be provided via `oauthClientFile` + `oauthRefreshToken` or the explicit client fields.
|
||||
- Env options (default account): `GOOGLE_CHAT_OAUTH_CLIENT_ID`, `GOOGLE_CHAT_OAUTH_CLIENT_SECRET`,
|
||||
`GOOGLE_CHAT_OAUTH_REDIRECT_URI`, `GOOGLE_CHAT_OAUTH_CLIENT_FILE`,
|
||||
`GOOGLE_CHAT_OAUTH_REFRESH_TOKEN`, `GOOGLE_CHAT_OAUTH_REFRESH_TOKEN_FILE`.
|
||||
- `oauthFromGog` reuses the `gog` keyring. Use `gogAccount`/`gogClient` (or `GOG_ACCOUNT`/`GOG_CLIENT`) when multiple accounts or clients exist.
|
||||
- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
|
||||
- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
|
||||
- `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth).
|
||||
|
||||
@@ -1140,6 +1140,12 @@ Multi-account support lives under `channels.googlechat.accounts` (see the multi-
|
||||
"googlechat": {
|
||||
enabled: true,
|
||||
serviceAccountFile: "/path/to/service-account.json",
|
||||
oauthClientFile: "/path/to/oauth-client.json",
|
||||
oauthRefreshToken: "1//0g...",
|
||||
// Or reuse gog OAuth:
|
||||
// oauthFromGog: true,
|
||||
// gogAccount: "you@example.com",
|
||||
// gogClient: "work",
|
||||
audienceType: "app-url", // app-url | project-number
|
||||
audience: "https://gateway.example.com/googlechat",
|
||||
webhookPath: "/googlechat",
|
||||
@@ -1164,6 +1170,12 @@ Multi-account support lives under `channels.googlechat.accounts` (see the multi-
|
||||
Notes:
|
||||
- Service account JSON can be inline (`serviceAccount`) or file-based (`serviceAccountFile`).
|
||||
- Env fallbacks for the default account: `GOOGLE_CHAT_SERVICE_ACCOUNT` or `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
|
||||
- User OAuth can be provided via `oauthClientFile` + `oauthRefreshToken` (or explicit client fields).
|
||||
- Env fallbacks for user OAuth (default account): `GOOGLE_CHAT_OAUTH_CLIENT_ID`,
|
||||
`GOOGLE_CHAT_OAUTH_CLIENT_SECRET`, `GOOGLE_CHAT_OAUTH_REDIRECT_URI`,
|
||||
`GOOGLE_CHAT_OAUTH_CLIENT_FILE`, `GOOGLE_CHAT_OAUTH_REFRESH_TOKEN`,
|
||||
`GOOGLE_CHAT_OAUTH_REFRESH_TOKEN_FILE`.
|
||||
- `oauthFromGog` reuses `gog` OAuth credentials; `gogAccount`/`gogClient` (or `GOG_ACCOUNT`/`GOG_CLIENT`) select the account/client.
|
||||
- `audienceType` + `audience` must match the Chat app’s webhook auth config.
|
||||
- Use `spaces/<spaceId>` or `users/<userId|email>` when setting delivery targets.
|
||||
|
||||
|
||||
Reference in new issue
Block a user