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

Go to console.cloud.google.com
Click the project dropdown then New Project
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

Go to IAM & Admin then Service Accounts
Click Create Service Account
Enter name and description
Click Create and Continue
Skip the optional steps, click Done

4. Create service account key

Click on your service account
Go to Keys tab
Click Add Key then Create new key
Select JSON and click Create
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

Go to the Chat API configuration
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
Click Save

6. Add bot to a space

Open Google Chat
Create or open a Space
Click the space name then Manage apps & integrations
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

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

2. Grant Chat service account access

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

3. Create push subscription

Go to Pub/Sub then Subscriptions
Click Create Subscription
Select your topic
Set Delivery type to Push
Set Endpoint URL to https://your-domain.com/api/webhooks/gchat
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:

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

Step 2 — Authorize in Google Admin Console:

Go to Google Admin Console
Go to Security then Access and data control then API controls
Click Manage Domain Wide Delegation then Add new
Enter the numeric Client ID from Step 1

Add OAuth scopes (comma-separated, on one line):

https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.spaces.create

Click Authorize

Step 3 — Set environment variable:

Set GOOGLE_CHAT_IMPERSONATE_USER to an admin user email in your domain (e.g., admin@yourdomain.com).

Configuration

All options are auto-detected from environment variables when not provided.

Option	Required	Description
`credentials`	No*	Service account credentials JSON. Auto-detected from `GOOGLE_CHAT_CREDENTIALS`
`useApplicationDefaultCredentials`	No	Use Application Default Credentials. Auto-detected from `GOOGLE_CHAT_USE_ADC`
`pubsubTopic`	No	Pub/Sub topic for Workspace Events. Auto-detected from `GOOGLE_CHAT_PUBSUB_TOPIC`
`pubsubAudience`	No	Expected JWT audience for Pub/Sub webhook verification. Auto-detected from `GOOGLE_CHAT_PUBSUB_AUDIENCE`
`googleChatProjectNumber`	No	GCP project number for direct webhook JWT verification. Auto-detected from `GOOGLE_CHAT_PROJECT_NUMBER`
`impersonateUser`	No	User email for domain-wide delegation. Auto-detected from `GOOGLE_CHAT_IMPERSONATE_USER`
`auth`	No	Custom auth object (advanced)
`logger`	No	Logger instance (defaults to `ConsoleLogger("info")`)

*Either credentials, GOOGLE_CHAT_CREDENTIALS env var, useApplicationDefaultCredentials, or GOOGLE_CHAT_USE_ADC=true is required.

Environment variables

GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}

# Optional: for receiving all messages
GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com

# Optional: webhook verification (recommended for production)
GOOGLE_CHAT_PROJECT_NUMBER=123456789          # For direct webhook JWT verification
GOOGLE_CHAT_PUBSUB_AUDIENCE=https://your-domain.com/api/webhooks/gchat  # For Pub/Sub JWT verification

Webhook verification

The adapter supports JWT verification for both webhook types. When configured, the adapter validates the Authorization: Bearer <JWT> header on incoming requests using Google's public keys. Requests with missing or invalid tokens are rejected with HTTP 401.

Verification is opt-in — when the config options are not set, webhooks are accepted without signature checks (for backward compatibility and development).

Direct webhooks (Google Chat API)

Google Chat sends a signed JWT with every webhook request. The JWT audience (aud claim) is your GCP project number.

createGoogleChatAdapter({
  googleChatProjectNumber: "123456789",
});

Find your project number in the GCP Console dashboard (it's different from the project ID).

Pub/Sub push messages

Google Cloud Pub/Sub sends a signed OIDC JWT with push deliveries. The JWT audience is whatever you configured on the push subscription.

createGoogleChatAdapter({
  pubsubAudience: "https://your-domain.com/api/webhooks/gchat",
});

To enable authenticated push on your Pub/Sub subscription:

Go to Pub/Sub then Subscriptions
Edit your push subscription
Enable Authentication
Select a service account with the Service Account Token Creator role
Set the Audience to your webhook URL
Use the same URL as GOOGLE_CHAT_PUBSUB_AUDIENCE

Features

Messaging

Feature	Supported
Post message	Yes
Edit message	Yes
Delete message	Yes
File uploads	No
Streaming	Post+Edit fallback

Rich content

Feature	Supported
Card format	Google Chat Cards
Buttons	Yes
Link buttons	Yes
Select menus	Yes
Tables	ASCII
Fields	Yes
Images in cards	Yes
Modals	No

Conversations

Feature	Supported
Slash commands	No
Mentions	Yes
Add reactions	Yes (via Workspace Events)
Remove reactions	Yes (via Workspace Events)
Typing indicator	No
DMs	Yes (requires delegation)
Ephemeral messages	Yes (native)

Message history

Feature	Supported
Fetch messages	Yes
Fetch single message	No
Fetch thread info	Yes
Fetch channel messages	Yes
List threads	Yes
Fetch channel info	Yes
Post channel message	Yes

Limitations

Typing indicators: Not supported by Google Chat API. startTyping() is a no-op.
Adding reactions: The Google Chat API doesn't support service account (app) authentication for adding reactions. To use addReaction() or removeReaction(), you need domain-wide delegation with impersonateUser configured — but the reaction appears as coming from the impersonated user, not the bot.

Message history (`fetchMessages`)

Fetching message history requires domain-wide delegation with the impersonateUser config option set. The impersonated user must have access to the spaces you want to read from. See the Pub/Sub setup above for configuring delegation and OAuth scopes.

Troubleshooting

401 Unauthorized on webhooks

For direct webhooks: verify GOOGLE_CHAT_PROJECT_NUMBER matches your GCP project number (not project ID)
For Pub/Sub: verify GOOGLE_CHAT_PUBSUB_AUDIENCE matches the audience configured on your push subscription
Check that authentication is enabled on your Pub/Sub push subscription
Ensure the service account used for push authentication has the Service Account Token Creator role

No webhook received

Verify the App URL is correct in Google Chat configuration
Check that the Chat API is enabled
Ensure the service account has the necessary permissions

Pub/Sub not working

Verify chat-api-push@system.gserviceaccount.com has Pub/Sub Publisher role
Check that the push subscription URL is correct
Verify domain-wide delegation is configured with correct scopes
Check GOOGLE_CHAT_IMPERSONATE_USER is a valid admin email

"Permission denied" for Workspace Events

Ensure domain-wide delegation is configured
Verify the OAuth scopes are exactly as specified
Check that the impersonated user has access to the spaces

"Insufficient Permission" for DMs

DMs require domain-wide delegation with chat.spaces and chat.spaces.create scopes
Scope changes can take up to 24 hours to propagate

Button clicks not received

Verify Interactive features is enabled in the Google Chat app configuration
Check that the App URL is correctly set and accessible
Button clicks go to the same webhook URL as messages

License

MIT

README.md

@chat-adapter/gchat

Installation

Usage