package
Google Chat adapter for Chat SDK — service account auth, Card v2, dialogs, and Workspace Events
npm install @chat-adapter/gchatGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
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
pnpm add @chat-adapter/gchatTo scaffold a new Google Chat bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter gchat memoryVisit the adapters directory to see other available official and vendor-official adapters.
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!");
});Go to APIs & Services then Library and enable:
GOOGLE_CHAT_CREDENTIALSNote: If your organization has the
iam.disableServiceAccountKeyCreationconstraint enabled, you need to relax it or add an exception for your project in IAM & Admin then Organization Policies.
https://your-domain.com/api/webhooks/gchatBy 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.
chat-events)GOOGLE_CHAT_PUBSUB_TOPIC (format: projects/your-project-id/topics/chat-events)chat-api-push@system.gserviceaccount.comhttps://your-domain.com/api/webhooks/gchatGOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAILDomain-wide delegation is required for creating Workspace Events subscriptions and initiating DMs.
Step 1 — Enable delegation on the service account:
Step 2 — Authorize in Google Admin Console:
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.createStep 3 — Set environment variable:
Set GOOGLE_CHAT_IMPERSONATE_USER to an admin user email in your domain (e.g., admin@yourdomain.com).
Most options are auto-detected from environment variables when not provided.
endpointUrl must be passed in config.
| Option | Required | Description |
|---|---|---|
credentials | No* | Service account credentials JSON. Auto-detected from GOOGLE_CHAT_CREDENTIALS |
botUserId | No | Canonical users/... resource name of this Chat app. Required for exact self-message and mention detection. Auto-detected from GOOGLE_CHAT_BOT_USER_ID |
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 |
pubsubServiceAccountEmail | No§ | Service account your Pub/Sub push subscription authenticates as. Required to accept Pub/Sub pushes. Auto-detected from GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL |
googleChatProjectNumber | No† | GCP project number for direct webhook JWT verification when the Chat app's authentication audience is "Project number". Auto-detected from GOOGLE_CHAT_PROJECT_NUMBER |
endpointUrl | No† | Public webhook URL for button click routing and direct webhook JWT verification when the Chat app's authentication audience is "HTTP endpoint URL". Must be passed in config |
workspaceAddOnServiceAccountEmail | No‡ | Your own service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com identity. Required to accept Workspace Add-on Chat app webhooks. Auto-detected from GOOGLE_CHAT_WORKSPACE_ADDON_SERVICE_ACCOUNT_EMAIL |
disableSignatureVerification | No† | Disable JWT verification entirely (development only). Auto-detected from GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true |
impersonateUser | No | User email for domain-wide delegation. Auto-detected from GOOGLE_CHAT_IMPERSONATE_USER |
auth | No | Custom auth object (advanced) |
apiUrl | No | Override the Google Chat API base URL. Auto-detected from GOOGLE_CHAT_API_URL |
logger | No | Logger instance (defaults to ConsoleLogger("info")) |
*Either credentials, GOOGLE_CHAT_CREDENTIALS env var, useApplicationDefaultCredentials, or GOOGLE_CHAT_USE_ADC=true is required.
Use the canonical sender.name from a verified message authored by your Chat app for botUserId. The adapter does not learn its identity from inbound mentions. Without this value it conservatively treats every BOT sender as self to prevent reply loops.
With botUserId set, the adapter reads message.isMention from the message's USER_MENTION annotations, for webhook, Pub/Sub, and fetched messages. It is true when an annotation names your Chat app and false otherwise, so in a space a plain-text @name without a mention annotation doesn't reach onNewMention. Direct messages are still routed as mentions when no onDirectMessage handler is registered. The app's mention in message.text is rewritten to @{userName}. The adapter logs a warning at startup if botUserId isn't a users/... resource name, and once if a message mentions an app whose ID differs from botUserId.
Without botUserId, the adapter can't identify your Chat app in annotations. A message that only mentions people gets isMention: false. Every other message falls back to matching @{userName} in the text. That match needs userName to be your app's display name in Google Chat, and it also matches another app whose display name starts with userName followed by a space.
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.
†One of googleChatProjectNumber, endpointUrl, pubsubAudience, or disableSignatureVerification: true is required — the constructor throws otherwise. Configure the verifier(s) for each transport you actually receive; requests of a shape whose verifier is unconfigured are rejected with HTTP 401.
§Required alongside pubsubAudience. The audience is your public push endpoint, so anyone can have Google mint a validly signed token naming it from their own project. Only the email claim identifies the caller, which is why Google requires checking it in addition to aud. Without it, Pub/Sub pushes are rejected with HTTP 401 rather than trusted on their audience alone.
‡Only Workspace Add-on Chat apps need this. Their webhooks are signed by an add-on service identity rather than chat@system.gserviceaccount.com, and every add-on project shares the same service-{projectNumber}@gcp-sa-gsuiteaddons email shape — so the identity is only meaningful compared exactly. Without it, add-on tokens are rejected with HTTP 401 rather than trusted by shape. Standalone Chat apps are unaffected.
GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
GOOGLE_CHAT_BOT_USER_ID=users/123456789
# Optional: for receiving all messages
GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com
# Webhook verification — at least one verifier or the explicit opt-out is required
GOOGLE_CHAT_PROJECT_NUMBER=123456789 # Direct webhooks with project-number audience
GOOGLE_CHAT_PUBSUB_AUDIENCE=https://your-domain.com/api/webhooks/gchat # For Pub/Sub JWT verification
GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL=pubsub@your-project.iam.gserviceaccount.com # Push subscription identity
# Workspace Add-on Chat apps only — your own add-on service identity
GOOGLE_CHAT_WORKSPACE_ADDON_SERVICE_ACCOUNT_EMAIL=service-123456789@gcp-sa-gsuiteaddons.iam.gserviceaccount.com
# GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true # Escape hatch for local dev only
# Optional: override the Google Chat API base URL
GOOGLE_CHAT_API_URL=...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 required. The constructor throws ValidationError unless one of the following is set:
googleChatProjectNumber (or GOOGLE_CHAT_PROJECT_NUMBER) — direct webhooks when the Chat app's authentication audience is "Project number"endpointUrl — direct webhooks when the Chat app's authentication audience is "HTTP endpoint URL"; also required for routing card button clicks in HTTP endpoint apps. Workspace Add-on Chat apps additionally need workspaceAddOnServiceAccountEmail, since their tokens are signed by an add-on identity instead of chat@system.gserviceaccount.compubsubAudience (or GOOGLE_CHAT_PUBSUB_AUDIENCE) — Pub/Sub push deliveries. Also set pubsubServiceAccountEmail (or GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL) to the identity in your subscription's push auth settings, or pushes are rejecteddisableSignatureVerification: true (or GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true) — explicit opt-out, intended for local development onlyThe two transports share one HTTP endpoint, so each verifier only covers its own request shape. If you only configure a direct-webhook verifier, incoming Pub/Sub-shaped requests are rejected with HTTP 401, and vice versa — configure both if you receive both.
Google Chat sends a signed token with every webhook request. The expected JWT audience (aud claim) depends on the Chat app's Authentication audience setting:
createGoogleChatAdapter({
googleChatProjectNumber: "123456789",
});Use googleChatProjectNumber when the setting is Project number. Find your project number in the GCP Console dashboard (it's different from the project ID).
createGoogleChatAdapter({
endpointUrl: "https://your-domain.com/api/webhooks/gchat",
});Use endpointUrl when the setting is HTTP endpoint URL. Workspace Add-on Chat apps always use URL audience tokens. When both googleChatProjectNumber and endpointUrl are set, either token type is accepted.
The two modes carry different token types, and the adapter verifies each per Google's reference implementation: endpoint-URL tokens are standard Google OIDC ID tokens (checked against Google's public certs, plus the Chat service-account email claim with email_verified), while project-number tokens are JWTs self-signed by chat@system.gserviceaccount.com (checked against that service account's X.509 certificates with issuer chat@system.gserviceaccount.com). The configured endpointUrl must exactly match the URL registered in the Chat API console — a trailing-slash or scheme mismatch fails verification.
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:
GOOGLE_CHAT_PUBSUB_AUDIENCE| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| File uploads | No |
| Streaming | Post+Edit fallback |
| 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 |
| 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) |
| 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 |
startTyping() is a no-op.addReaction() or removeReaction(), you need domain-wide delegation with impersonateUser configured — but the reaction appears as coming from the impersonated user, not the bot.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.
GOOGLE_CHAT_PROJECT_NUMBER matches your GCP project number (not project ID)GOOGLE_CHAT_PUBSUB_AUDIENCE matches the audience configured on your push subscriptionchat-api-push@system.gserviceaccount.com has Pub/Sub Publisher roleGOOGLE_CHAT_IMPERSONATE_USER is a valid admin emailchat.spaces and chat.spaces.create scopesIf you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chatThe skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 32 packages.
5.7 MB
Includes dependencies.
4 direct · 2 outdated