Google Chat

サービスアカウント JWT 認証による Google Workspace Chat 連携。受信アクティビティは [email protected] で署名されます。

🟡 サービスアカウント経由の送信対応済み、受信は JWT 検証済み。 Google Workspace 環境向けです。送信時はサービスアカウント JSON キーから短命アクセストークンを発行し、受信時はすべての POST が [email protected] で署名されていることを検証します。

できること

テキスト送信（POST https://chat.googleapis.com/v1/{space}/messages、{text} 使用）。スレッド（thread.name）もサポートしています。
受信 webhook（/webhooks/google-chat）。Google が受信リクエストごとに [email protected] 発行のベアラー JWT で署名します。
アクセストークンキャッシュ（TTL 1 時間、5 分前に自動更新）。
今回はテキストのみ対応。 Cards v2、ダイアログ、スラッシュコマンド、添付ファイルのダウンロードは未対応です。
メッセージあたり 4096 文字制限。

セットアップ

1. Google Cloud プロジェクトとサービスアカウントを作成する

Google Cloud Console で Chat アプリ用のプロジェクトを選択（または新規作成）します。
「APIs & Services」→「Enable APIs」から Google Chat API を有効にします。
「IAM & Admin」→「Service Accounts」→「Create Service Account」を選択します。名前を決めてください（例: minara-chat-bot）。
作成後、サービスアカウントを開き「Keys」タブ→「Add Key」→「JSON」を選択します。ダウンロードしたファイルを保存してください。

2. Chat アプリを設定する

同じ Google Cloud プロジェクト内で Google Chat API→「Configuration」タブに移動します。
App name・Avatar URL・Description: 適切な値を設定してください。
Functionality: 「Receive 1:1 messages」と「Join spaces and group conversations」を有効にします。
Connection settings: 「App URL」を選択し、エンドポイントを https://<your-host>/webhooks/google-chat に設定します。
Authentication Audience: いずれかを選んで控えておきます。
- 「Project Number」を選ぶと、audience は 12 桁の GCP プロジェクト番号になります。
- 「HTTP endpoint URL」を選ぶと、audience はエンドポイント URL になります。
Permissions: 「Specific people and groups」またはドメイン全体を選択します。

3. サービスアカウント JSON をサンドボックスに移動する

CLAUDE.md §4 の規定により、サービスアカウントキーはデータ / サンドボックスのディレクトリ内に保存する必要があります。ダウンロードした JSON を ~/.minara/sandbox/（または MINARA_DATA_DIR に相当するパス）以下に移動してください。

mv ~/Downloads/<project>-<hash>.json ~/.minara/sandbox/google-chat-sa.json
chmod 600 ~/.minara/sandbox/google-chat-sa.json

4. デフォルトスペースを確認する

Chat アプリをスペースに追加（またはテストユーザーから Bot に DM）したあと、URL からスペースのリソース名を取得します。spaces/AAAA1234567 のような形式です。これを GOOGLE_CHAT_DEFAULT_SPACE_ID として保存します。

5. Minara を設定する

minara auth messaging add
# リストから `google_chat` を選択します。

または環境変数で直接設定します。

GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH=/Users/you/.minara/sandbox/google-chat-sa.json
GOOGLE_CHAT_DEFAULT_SPACE_ID=spaces/AAAA1234567
GOOGLE_CHAT_AUDIENCE=1234567890

GOOGLE_CHAT_AUDIENCE は Workspace コンソールの設定値と完全に一致させる必要があります。コンソールで「Project Number」を選んだ場合は数字のみ、「HTTP endpoint URL」を選んだ場合はコンソールに表示された URL（末尾スラッシュの有無も含めて）をそのまま設定してください。

6. テスト

minara auth messaging test google_chat

受信 webhook

Google の受信 JWT に含まれるクレームは以下のとおりです。

クレーム	期待値
`iss`（発行者）	`[email protected]`
`aud`（audience）	`GOOGLE_CHAT_AUDIENCE` と一致すること
署名	RS256、`https://www.googleapis.com/service_accounts/v1/jwk/[email protected]` に公開された X.509 証明書で検証
クロックスキュー	±5 分

JWKS は 24 時間キャッシュされます。kid の不一致が発生した場合は自動的にローテーションを処理します。

受け付けるイベントタイプは MESSAGE（アプリが参加しているスペースへのユーザー投稿）のみです。その他のタイプ（ADDED_TO_SPACE、REMOVED_FROM_SPACE、CARD_CLICKED）は破棄されます。

制限事項と注意点

GOOGLE_CHAT_AUDIENCE はバイト単位で完全一致が必要です。 受信時に 401 が返る最も一般的な原因は、環境変数の値がコンソール設定と一致していないことです。「Project Number」の場合は、先頭ゼロなしの数字文字列をそのまま設定してください。
サービスアカウント JSON のパスはサンドボックス内に置く必要があります。 CLAUDE.md §4（サンドボックス限定ファイル参照）の規定によります。ファクトリ関数は起動時にファイルを読み込むため、キーをローテーションする場合は再起動が必要です。
JSON 1 つ、audience 1 つのモデル。 コンソールで「Authentication Audience」を変更した場合は、同じタイミングで GOOGLE_CHAT_AUDIENCE も更新してください。
カードは未対応。 Cards v2 メッセージとダイアログは送受信ともに未実装です。

トラブルシューティング

「受信時に 401 Unauthorized」が発生する

GOOGLE_CHAT_AUDIENCE がコンソールの設定と一致していません。Chat API の Configuration ページを開き、audience の値をそのままコピーしてください。

「送信時に Missing required scope」が発生する

サービスアカウントに https://www.googleapis.com/auth/chat.bot スコープが付与されていません。ファクトリ関数が自動でリクエストしますが、サービスアカウントが Chat API を有効にしたプロジェクトと同じプロジェクトに属しているか確認してください。

「Service-account JSON not found」が発生する

GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH がサンドボックス外を指しているか、ファイルが存在しません。~/.minara/sandbox/ 以下に移動して環境変数を更新してください。

リファレンス

環境変数: GOOGLE_CHAT_*
送信: apps/agent/src/messaging/google_chat.ts
受信仕様: apps/agent/src/messaging/inbound/specs/google_chat.ts
JWT ヘルパー: apps/agent/src/messaging/_shared/jwt-verify.ts
リクエスト検証: developers.google.com / Verify requests from Chat

目次