Google Chat

Create a new bot

Scaffold a Next.js bot with the Google Chat adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

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

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

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

The memory state adapter keeps subscriptions and locks in process memory, which suits local development. Use Redis or PostgreSQL in production.

Platform setup

Configuration

One of googleChatProjectNumber, endpointUrl, pubsubAudience, or disableSignatureVerification: true is required, and the constructor throws otherwise. Configure a verifier for each transport you actually receive.

Set botUserId (or GOOGLE_CHAT_BOT_USER_ID) to the canonical sender.name from a verified message authored by your Chat app, such as users/123456789. The adapter never learns this identity from inbound mentions. When it is omitted, all BOT senders are conservatively treated as self to prevent reply loops.

Apps upgrading from an earlier release that rely on mention handlers must configure botUserId to preserve mention handling. Without it, bot mention annotations are left unchanged and the default onNewMention detection may no longer match them.

Environment variables

endpointUrl has no environment variable; pass it in config.

Webhook verification

Direct webhooks and Pub/Sub pushes share one HTTP endpoint, so each verifier covers only its own request shape:

• Direct webhooks: Google Chat sends a signed JWT in the Authorization: Bearer … header. The expected aud claim depends on how the Chat app is configured (see Verify requests from Google Chat).
• Pub/Sub push: Cloud Pub/Sub sends a signed OIDC JWT whose audience is whatever you configured on the push subscription. Configure both pubsubAudience and pubsubServiceAccountEmail.

If you configure only a direct-webhook verifier, incoming Pub/Sub-shaped requests are rejected with HTTP 401, and the reverse is also true. Configure both transports if you receive both.

Which direct-webhook option do I need?

The two token types are verified differently, matching Google's reference implementation: endpoint-URL tokens are standard OIDC ID tokens checked against Google's public certs plus the Chat service-account email claim; project-number tokens are self-signed by chat@system.gserviceaccount.com and checked against that service account's own X.509 certificates. When both googleChatProjectNumber and endpointUrl are set, either token type is accepted. If you don't know which mode your app uses, look at an incoming token: an email claim containing gcp-sa-gsuiteaddons means it's a Workspace Add-on (URL audience).

Pub/Sub for receiving all messages

By default, Google Chat sends webhooks only 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,
});

Topic and subscription

1. Under Pub/Sub then Topics, create a topic (for example, chat-events) and copy its full name to GOOGLE_CHAT_PUBSUB_TOPIC.
2. Add chat-api-push@system.gserviceaccount.com as a Pub/Sub Publisher.
3. Create a Push subscription with endpoint https://your-domain.com/api/webhooks/gchat. Enable authentication on it and pick a service account, then set that account's email as GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL.

Domain-wide delegation

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

1. In IAM & Admin then Service Accounts, edit your service account and check Enable Google Workspace Domain-wide Delegation. Copy the numeric Client ID.
2. In the Google Admin Console, go to Security then Access and data control then API controls, then Manage Domain Wide Delegation.
3. Add the Client ID with these comma-separated scopes:

   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

4. Set GOOGLE_CHAT_IMPERSONATE_USER to an admin email.

Limitations

• Typing indicators are not supported by the Google Chat API.
• Adding reactions: the Chat API doesn't allow service-account auth for reactions. With impersonateUser configured, the reaction appears as coming from the impersonated user.
• Message history (fetchMessages) requires domain-wide delegation with impersonateUser.

Feature support