Connect Google Chat

Google Chat is a chat platform alongside Slack and the web. The same identity and configuration carry across all three, and each person’s DMs share one personal scope.

Before you start

A Google Workspace account. Personal Google accounts cannot join spaces.
Permission to create a service account key in Google Cloud.
A public HTTPS endpoint for your Cengrid core.
A production deployment on Postgres: DATABASE_URL set, with SESSION_STORE=postgres and RUN_STORE=postgres.

Open Admin → Onboarding → Google Chat → Connect Google Chat. The panel walks through the same six steps below.

Setup

Configure the Chat app. In Google Cloud, enable the Google Chat API (chat.googleapis.com) and open Configuration.
- Clear Build this Chat app as a Google Workspace add-on.
- Set the app name (for example Cengrid), a 512×512 PNG avatar URL and a description.
- Turn Enable interactive features on, and under Functionality select Join spaces and group conversations.
Set the endpoint. Use one HTTP endpoint URL for all triggers:
```
https://<your-core-host>/v1/platforms/google-chat/events
```
Set Authentication Audience to HTTP endpoint URL (not Project Number). The URL entered in Cengrid must match Google’s exactly, including any trailing slash. Under Visibility, add the people who should be able to use the app.
Create a service account. Create one, for example cengrid-chat, with no project role, and create a JSON key. In the Cengrid panel choose Choose JSON key. The key must be RSA, at least 2048 bits, with a client_email ending in .gserviceaccount.com. It is encrypted before storage.
Add the app to private spaces. Spaces must be private, have no external members, and have people added individually, not through Google Groups. Then choose Load space members in the panel.
Map identities. Either enable Sync Workspace contacts automatically (see below) or map each Google Chat user to a work email by hand.
Validate and connect. Choose Validate and connect. Validation sends no message. Then open Admin → Rooms → Add room → Google Chat to add each space, and mention the app in a thread.

Only spaces added on Rooms are served. DMs run in the sender’s personal scope, and group chats are ignored.

Workspace directory sync

Directory sync maps Chat users to work emails automatically. It needs domain-wide delegation for the service account:

Enable the Admin SDK API in the project.
Enable domain-wide delegation on the service account and copy its numeric client ID.
As a Workspace super admin, open Security → Access and data control → API controls → Manage Domain Wide Delegation, add that client ID, and authorise only https://www.googleapis.com/auth/admin.directory.user.readonly.
In Cengrid, enter a delegated admin email that can read all users and your immutable Customer ID. It must begin with C, and my_customer is rejected.

The directory refreshes about every minute. Directory sync is the only place domain-wide delegation is used.

Scopes

Purpose	Scope
Sending messages and reading space membership	`chat.bot`. Needs no Workspace admin approval.
Native thread history (optional)	`chat.app.messages.readonly`. A Workspace admin must authorise it through Google’s app authorisation.
Directory sync (optional)	`admin.directory.user.readonly`, with domain-wide delegation

Environment-managed setup

You can configure the platform with environment variables instead of the panel. Settings saved in the panel override environment values, and a disconnect record overrides them too.

Variable	Meaning
`GOOGLE_CHAT_AUDIENCE`	The HTTP endpoint URL. An `https` URL with no credentials or fragment.
`GOOGLE_CHAT_SERVICE_ACCOUNT_JSON`	The service account key. A secret.
`GOOGLE_CHAT_USER_PRINCIPALS`	JSON map such as `{"users/123":"alex@example.com"}`. May be `{}` in directory mode.
`GOOGLE_CHAT_DIRECTORY_SUBJECT`	The delegated admin email for directory sync.
`GOOGLE_CHAT_DIRECTORY_CUSTOMER_ID`	Customer ID, starting with `C`.
`GOOGLE_CHAT_NATIVE_THREAD_HISTORY`	`true` or `false`.
`WEB_UI_PUBLIC_URL`	Used for links to generated files.

How requests are verified

Cengrid accepts a request only if its bearer token comes from https://accounts.google.com, has your endpoint URL as its audience, is issued to chat@system.gserviceaccount.com, and has a verified email. A reverse proxy in front of core must preserve the Authorization header.