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.
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
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
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
Set GOOGLE_CHAT_IMPERSONATE_USER to an admin user email in your domain (e.g., admin@yourdomain.com).
Configuration
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.
Environment variables
GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}GOOGLE_CHAT_BOT_USER_ID=users/123456789# Optional: for receiving all messagesGOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-eventsGOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com# Webhook verification — at least one verifier or the explicit opt-out is requiredGOOGLE_CHAT_PROJECT_NUMBER=123456789 # Direct webhooks with project-number audienceGOOGLE_CHAT_PUBSUB_AUDIENCE=https://your-domain.com/api/webhooks/gchat # For Pub/Sub JWT verificationGOOGLE_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 identityGOOGLE_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 URLGOOGLE_CHAT_API_URL=...
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 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.com
pubsubAudience (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 rejected
disableSignatureVerification: true (or GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true) — explicit opt-out, intended for local development only
The 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.
Direct webhooks (Google Chat API)
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:
Use googleChatProjectNumber when the setting is Project number. Find your project number in the GCP Console dashboard (it's different from the project ID).
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.
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.
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
AI Coding Agents
If 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/chat
The 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-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.