@chat-adapter/gchat weekly downloads statistics

@chat-adapter/gchat

npm package: @chat-adapter/gchat

Google Chat adapter for Chat SDK. Configure with service account authentication and optional Pub/Sub.

Documentation: chat-sdk.dev/adapters/official/gchat · Guides: vercel.com/kb/chat-sdk

Installation

pnpm add @chat-adapter/gchat

Scaffold with the CLI

To scaffold a new Google Chat bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter gchat memory

Visit the adapters directory to see other available official and vendor-official adapters.

Usage

The adapter auto-detects credentials from GOOGLE_CHAT_CREDENTIALS or GOOGLE_CHAT_USE_ADC environment variables:

import { Chat } from "chat";
import { createGoogleChatAdapter } from "@chat-adapter/gchat";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    gchat: createGoogleChatAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Google Chat!");
});

Google Chat setup

1. Create a GCP project

1. Go to console.cloud.google.com
2. Click the project dropdown then New Project
3. Enter project name and click Create

2. Enable required APIs

Go to APIs & Services then Library and enable:

• Google Chat API
• Google Workspace Events API (for receiving all messages)
• Cloud Pub/Sub API (for receiving all messages)

3. Create a service account

1. Go to IAM & Admin then Service Accounts
2. Click Create Service Account
3. Enter name and description
4. Click Create and Continue
5. Skip the optional steps, click Done

4. Create service account key

1. Click on your service account
2. Go to Keys tab
3. Click Add Key then Create new key
4. Select JSON and click Create
5. Copy the entire JSON content as GOOGLE_CHAT_CREDENTIALS

Note: If your organization has the iam.disableServiceAccountKeyCreation constraint enabled, you need to relax it or add an exception for your project in IAM & Admin then Organization Policies.

5. Configure Google Chat app

1. Go to the Chat API configuration
2. Click Configuration and fill in:
   • App name: Your bot's display name
   • Avatar URL: URL to your bot's avatar
   • Description: What your bot does
   • Interactive features: Enable Receive 1:1 messages and Join spaces and group conversations
   • Connection settings: Select App URL
   • App URL: https://your-domain.com/api/webhooks/gchat
   • Visibility: Choose who can discover your app
3. Click Save

6. Add bot to a space

1. Open Google Chat
2. Create or open a Space
3. Click the space name then Manage apps & integrations
4. Click Add apps, search for your app, and click Add

Pub/Sub for all messages (optional)

By default, Google Chat only sends webhooks for @mentions. To receive all messages in a space, set up Workspace Events with Pub/Sub.

createGoogleChatAdapter({
  pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
  impersonateUser: process.env.GOOGLE_CHAT_IMPERSONATE_USER,
});

GOOGLE_CHAT_PUBSUB_TOPIC and GOOGLE_CHAT_IMPERSONATE_USER are also auto-detected from env vars, so you can omit them from config if the env vars are set.

1. Create Pub/Sub topic

1. Go to Pub/Sub then Topics
2. Click Create Topic
3. Enter topic ID (e.g., chat-events)
4. Uncheck Add a default subscription
5. Click Create
6. Copy the full topic name as GOOGLE_CHAT_PUBSUB_TOPIC (format: projects/your-project-id/topics/chat-events)

2. Grant Chat service account access

1. Go to your Pub/Sub topic
2. Click Permissions tab
3. Click Add Principal
4. Enter chat-api-push@system.gserviceaccount.com
5. Select role Pub/Sub Publisher
6. Click Save

3. Create push subscription

1. Go to Pub/Sub then Subscriptions
2. Click Create Subscription
3. Select your topic
4. Set Delivery type to Push
5. Set Endpoint URL to https://your-domain.com/api/webhooks/gchat
6. Check Enable authentication and pick a service account. This is what signs the OIDC token on each push, and its email is the value you set as GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL
7. Click Create

4. Enable domain-wide delegation

Domain-wide delegation is required for creating Workspace Events subscriptions and initiating DMs.

Step 1 — Enable delegation on the service account:

1. Go to IAM & Admin then Service Accounts
2. Click on your service account
3. Check Enable Google Workspace Domain-wide Delegation and save
4. Copy the Client ID (a numeric ID, not the email)

Step 2 — Authorize in Google Admin Console:…