Google Chat Adapter

Installation

npm install @chat-adapter/gchat

Environment Variables

Create a Google Chat app in the Google Cloud Console.

Variable	Required	Description
`GOOGLE_CHAT_CREDENTIALS`	Service Account	JSON service account key (entire contents)
`GOOGLE_CHAT_USE_ADC`	ADC/Workload Identity	Set to `true` to use Application Default Credentials
`GOOGLE_CHAT_PUBSUB_TOPIC`	Optional	Pub/Sub topic for Workspace Events (format: `projects/my-project/topics/my-topic`)
`GOOGLE_CHAT_IMPERSONATE_USER`	DM creation	User email for domain-wide delegation

Configuration Options

interface GoogleChatAdapterConfig {
  /** Service account credentials JSON (use OR useApplicationDefaultCredentials) */
  credentials?: ServiceAccountCredentials;
  /** Use Application Default Credentials (ADC) */
  useApplicationDefaultCredentials?: boolean;
  /** Custom auth client (e.g., Vercel OIDC) */
  auth?: GoogleAuth;
  /** HTTP endpoint URL for button click actions */
  endpointUrl?: string;
  /** User email to impersonate (domain-wide delegation) */
  impersonateUser?: string;
  /** Logger instance */
  logger: Logger;
  /** Pub/Sub topic for receiving all messages */
  pubsubTopic?: string;
  /** Override bot username */
  userName?: string;
}

Setup

Service Account
Application Default Credentials
Workload Identity Federation

Use a JSON service account key:

import { Chat } from 'chat';
import { createGoogleChatAdapter } from '@chat-adapter/gchat';
import { MemoryState } from '@chat-adapter/state-memory';

const chat = new Chat({
  userName: 'my-bot',
  adapters: {
    gchat: createGoogleChatAdapter({
      credentials: JSON.parse(process.env.GOOGLE_CHAT_CREDENTIALS!),
      pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
    }),
  },
  state: new MemoryState(),
});

await chat.initialize();

Use ADC (works with Workload Identity, GCE, Cloud Run, or gcloud auth):

import { Chat } from 'chat';
import { createGoogleChatAdapter } from '@chat-adapter/gchat';
import { MemoryState } from '@chat-adapter/state-memory';

const chat = new Chat({
  userName: 'my-bot',
  adapters: {
    gchat: createGoogleChatAdapter({
      useApplicationDefaultCredentials: true,
      pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
    }),
  },
  state: new MemoryState(),
});

await chat.initialize();

Use Vercel OIDC or other external identity:

import { GoogleAuth } from 'google-auth-library';

const auth = new GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/chat.bot'],
  // ... Workload Identity Federation config
});

const chat = new Chat({
  userName: 'my-bot',
  adapters: {
    gchat: createGoogleChatAdapter({
      auth,
      pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
    }),
  },
  state: new MemoryState(),
});

Webhook Handler

app.post('/webhooks/gchat', async (req, res) => {
  const response = await gchat.handleWebhook(req, {
    waitUntil: (promise) => {/* handle async work */},
  });
  res.status(response.status).send(await response.text());
});

Workspace Events (Recommended)

Why Workspace Events? Direct webhooks only fire for @mentions. Workspace Events delivers ALL messages via Pub/Sub, enabling background processing and better UX.

Create Pub/Sub topic

gcloud pubsub topics create gchat-events \
  --project=my-project

Configure adapter

Set pubsubTopic in your adapter config:

pubsubTopic: 'projects/my-project/topics/gchat-events'

Enable domain-wide delegation

Required for creating subscriptions:

Go to Google Workspace Admin Console
Security → API Controls → Domain-wide Delegation
Add your service account client ID
Authorize scopes:
- https://www.googleapis.com/auth/chat.bot
- https://www.googleapis.com/auth/chat.messages.readonly

Set impersonateUser to a user email in your workspace:

impersonateUser: '[email protected]'

Create Pub/Sub push subscription

Point subscription to your webhook endpoint:

gcloud pubsub subscriptions create gchat-webhook \
  --topic=gchat-events \
  --push-endpoint=https://your-app.com/webhooks/gchat

Subscribe to threads

When bot joins a space or a thread is subscribed, the adapter auto-creates a Workspace Events subscription:

// Subscriptions are created automatically when:
await thread.subscribe(async (msg) => {
  // This triggers Workspace Events subscription creation
});

Features

Supported Events

MESSAGE - Messages in spaces (via direct webhook or Pub/Sub)
ADDED_TO_SPACE - Bot added to a space
REMOVED_FROM_SPACE - Bot removed from a space
CARD_CLICKED - Button clicks in cards
message.v1.created (Pub/Sub) - All messages via Workspace Events
reaction.v1.created / reaction.v1.deleted (Pub/Sub) - Reactions

Cards v2

Google Chat uses Cards v2 format:

import { Card, Section, Button } from 'chat/cards';

await thread.post(
  <Card title="Deployment Status">
    <Section text="Build #42 ready to deploy" />
    <Button actionId="deploy" style="primary">Deploy Now</Button>
    <Button actionId="cancel">Cancel</Button>
  </Card>
);

HTTP Endpoint Apps: Cards require endpointUrl config (auto-detected from webhook URL). Button clicks route via this URL.

Reactions

Add/remove emoji reactions:

await thread.addReaction(messageId, { name: 'thumbs_up' });
await thread.removeReaction(messageId, { name: 'thumbs_up' });

Supported emojis: Standard Unicode emoji (👍, ❤️, 🎉, etc.)

Ephemeral Messages

Send private messages visible only to one user:

await thread.postEphemeral(userId, 'This is only visible to you');

File Attachments

File uploads are not yet supported. Use external links or Google Drive attachments instead.

Thread IDs

Google Chat thread IDs encode space and thread names:

gchat:{spaceName}:{base64(threadName)}

Examples:

DM (no thread): gchat:spaces/AAAAxxxx:
Space thread: gchat:spaces/AAAAxxxx:dGhyZWFkcy95eXl5

For DMs, thread name is omitted to treat the entire DM as one subscription target.

Opening DMs

Create a 1:1 conversation with a user:

const dmThreadId = await gchat.openDM(userId);
await chat.getThread(dmThreadId).post('Hello!');

Requires domain-wide delegation with impersonateUser configured.

Message History

Fetch message history (requires domain-wide delegation):

const { messages, nextCursor } = await thread.fetchMessages({
  limit: 100,
  direction: 'backward',
});

Platform Limits

Message length: 4,096 characters
Cards per message: 100 cards
Widgets per card: 100 widgets
Rate limits: Google Chat quotas

Code Examples

chat.onNewMention(async (event) => {
  await event.thread.post(`Hi ${event.message.author.userName}!`);
});

Troubleshooting

Bot only receives @mentions

Enable Workspace Events (Pub/Sub) to receive all messages
Without Pub/Sub, Google Chat only sends @mention events

Workspace Events subscription fails

Enable domain-wide delegation in Workspace Admin Console
Set impersonateUser to a user in your workspace
Grant service account https://www.googleapis.com/auth/chat.bot scope
Ensure Pub/Sub topic exists and is accessible

Button clicks don't work

For HTTP Endpoint apps: ensure endpointUrl is configured
Verify webhook URL is publicly accessible (HTTPS required)
Check Google Cloud Console logs for errors

openDM() fails

Requires domain-wide delegation with impersonateUser
Service account needs chat.spaces.create scope
User must be in same Workspace

Required Scopes

Add these OAuth scopes to your service account: Bot Scopes:

https://www.googleapis.com/auth/chat.bot - Core bot functionality
https://www.googleapis.com/auth/chat.messages.readonly - Read messages
https://www.googleapis.com/auth/chat.messages.reactions.create - Add reactions
https://www.googleapis.com/auth/chat.messages.reactions - Read/remove reactions
https://www.googleapis.com/auth/chat.spaces.create - Create DMs (with domain-wide delegation)

See Google Chat scopes for details.

Next Steps

Message Handling

Process messages and build conversation flows

Cards v2

Create interactive UIs with Google Chat cards

Workspace Events

Learn about Workspace Events API

State Management

Persist subscriptions and data

Get Started

Core Concepts

Features

Adapters

State Management

Guides

Google Chat Adapter

Installation

Environment Variables

Configuration Options

Setup

Webhook Handler

Workspace Events (Recommended)

Features

Supported Events

Cards v2

Reactions

Ephemeral Messages

File Attachments

Thread IDs

Opening DMs

Message History

Platform Limits

Code Examples

Troubleshooting

Required Scopes

Next Steps

Message Handling

Cards v2

Workspace Events

State Management

Get Started

Core Concepts

Features

Adapters

State Management

Guides

​Installation

​Environment Variables

​Configuration Options

​Setup

​Webhook Handler

​Workspace Events (Recommended)

​Features

​Supported Events

​Cards v2

​Reactions

​Ephemeral Messages

​File Attachments

​Thread IDs

​Opening DMs

​Message History

​Platform Limits

​Code Examples

​Troubleshooting

​Required Scopes

​Next Steps

Message Handling

Cards v2

Workspace Events

State Management

Installation

Environment Variables

Configuration Options

Setup

Webhook Handler

Workspace Events (Recommended)

Features

Supported Events

Cards v2

Reactions

Ephemeral Messages

File Attachments

Thread IDs

Opening DMs

Message History

Platform Limits

Code Examples

Troubleshooting

Required Scopes

Next Steps