> ## Documentation Index > Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Google Chat > Install the Atoll Google Chat app and send mention notifications to Chat. Atoll can send mention notifications to Google Chat direct messages. Workspace administrators can install the Atoll Chat app for everyone in the domain, or for selected groups and organizational units. ## Requirements * A Google Workspace account with Google Chat access. The Workspace domain can be different from Atoll's production app domain. * Google Workspace administrator access for domain-wide installation in the Workspace domain you use for rollout. * A Google Cloud project owned by the Google account or Workspace organization that will configure the Chat app. * The Atoll Google Chat app configured in Google Cloud with the Chat API enabled and interactive features pointed at Atoll. * `GOOGLE_CHAT_AUDIENCE` or `GOOGLE_CHAT_CALLBACK_URL` set to the HTTPS callback URL configured in Google Chat. If neither is set, Atoll derives the callback from `NEXT_PUBLIC_APP_URL`. * Google application credentials that can request the `https://www.googleapis.com/auth/chat.bot` scope. * `GOOGLE_CHAT_APP_URL` set to a dedicated Atoll Chat app/listing URL when available. If unset, Atoll opens Google Chat directly. * `GOOGLE_CHAT_ADMIN_INSTALL_URL` set to the Workspace admin install URL. Set `GOOGLE_CHAT_MARKETPLACE_LISTING_URL` when a Marketplace listing is available. * Atoll organization owner or admin access. ## Google Cloud setup Use one Cloud project for the Chat app. Google's Chat API configuration controls the app identity users see in Chat, while the Marketplace SDK controls listing visibility and admin installation. The Google Workspace account/domain and the Atoll production domain do not need to match. For example, you can configure and test the Chat app from a Workspace account on one domain while the app callback, support, privacy, and terms URLs live on `atollhq.com`. ### 1. Prepare URLs and assets Before opening Google Cloud, decide these values: | Item | Value | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | Chat callback URL | `https://atollhq.com/api/integrations/google-chat/events` | | App name | `Atoll` | | Avatar URL | `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-avatar-256.png` | | Description | `Atoll mention notifications` | | Support URL | `https://atollhq.com/about` | | Privacy policy URL | `https://atollhq.com/legal/privacy` | | Terms URL | `https://atollhq.com/legal/terms` | The callback URL must be the same URL that Google Chat sends interaction events to and that Atoll verifies as the request audience. Prepared asset files are committed under `agent-pm/public/google-chat/` and are also uploaded to Supabase storage: | Asset | Local file | Public URL | | --------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Chat avatar, 256x256 | `agent-pm/public/google-chat/atoll-chat-avatar-256.png` | `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-avatar-256.png` | | Marketplace icon, 128x128 | `agent-pm/public/google-chat/atoll-chat-marketplace-icon-128.png` | `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-marketplace-icon-128.png` | | Marketplace icon, 32x32 | `agent-pm/public/google-chat/atoll-chat-marketplace-icon-32.png` | `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-marketplace-icon-32.png` | | Marketplace banner, 220x140 | `agent-pm/public/google-chat/atoll-chat-marketplace-banner-220x140.png` | `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-marketplace-banner-220x140.png` | After the app deploys with these files, the same assets will also be available from `https://atollhq.com/google-chat/...`. Suggested Marketplace copy: | Field | Suggested value | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Short description | `Get Atoll mention notifications in Google Chat.` | | Detailed description | `Atoll sends direct-message notifications in Google Chat when someone mentions you in an Atoll task. Workspace admins install the Chat app, and each user links their own direct message with a one-time command from Atoll profile settings.` | | Setup URL | `https://docs.atollhq.com/integrations/google-chat` | | Admin config URL | `https://docs.atollhq.com/integrations/google-chat` | | Developer email | `support@atollhq.com` | The remaining Marketplace asset is the screenshot. Capture it after the production app is deployed and the Chat app can be installed. Best screenshot: a Google Chat direct message with the Atoll app showing a successful connection or mention notification, with the Atoll profile notification settings visible only if you need a second screenshot. ### 2. Enable APIs 1. Open the Google Cloud project. 2. Configure the OAuth consent screen for the project. 3. Enable the Google Chat API. 4. Enable the Google Workspace Marketplace SDK. Google's setup docs: * [Configure the Google Chat API](https://developers.google.com/workspace/chat/configure-chat-api) * [Configure your app in the Google Workspace Marketplace SDK](https://developers.google.com/workspace/marketplace/enable-configure-sdk) ### 3. Configure the Chat API In Google Cloud Console, open **APIs & Services > Google Chat API > Configuration**. Set **Application info**: * **App name:** `Atoll`. * **Avatar URL:** `https://njkleeczlhowxkaszvii.supabase.co/storage/v1/object/public/attachments/public/google-chat/atoll-chat-avatar-256.png`. * **Description:** `Atoll mention notifications`. Set **Interactive features**: * Enable interactive features. * Under **Functionality**, leave **Join spaces and group conversations** unchecked for the first rollout. Atoll currently delivers mention notifications through direct messages with the Chat app. Enable this later only if you want the app to be addable to group spaces. * Under **Connection settings**, choose **HTTP endpoint URL**. * If Google shows **Triggers**, select **Specify an HTTP endpoint URL for each trigger** and enter the same Atoll callback URL in every required field: | Trigger field | Value | | ------------------ | --------------------------------------------------------- | | App command | `https://atollhq.com/api/integrations/google-chat/events` | | Added to space | `https://atollhq.com/api/integrations/google-chat/events` | | Message | `https://atollhq.com/api/integrations/google-chat/events` | | Removed from space | `https://atollhq.com/api/integrations/google-chat/events` | * Do not add slash commands in the **Commands** section for this version. Atoll links users by parsing the generated one-time setup message in a normal direct message, not by using a slash command. * Do not add **Link previews** for this version. * Under **Visibility** during testing, check **Make this chat app available to specific people and groups** and enter your own Google Workspace email address or a test Google Group from the Workspace domain you are using for setup. To make the app available beyond that test domain, publish/install it through the Google Workspace Marketplace flow below. * Under **Logs**, check **Log errors to Logging** so callback and configuration errors are visible in Google Cloud Logs Explorer. * **Authentication audience:** choose the HTTP endpoint URL option and use `https://atollhq.com/api/integrations/google-chat/events`. Google Chat sends `MESSAGE`, `ADDED_TO_SPACE`, and `REMOVED_FROM_SPACE` events to this endpoint. Atoll uses direct-message `MESSAGE` events to consume one-time setup messages and `REMOVED_FROM_SPACE` to revoke a user's link when the app is removed from that direct message. ### 4. Create app credentials Atoll sends Google Chat messages with app authentication and the `https://www.googleapis.com/auth/chat.bot` scope. 1. In Google Cloud Console, open **IAM & Admin > Service Accounts**. 2. Create a service account for the Chat app, for example `atoll-chat`. 3. Create a JSON key for the service account. 4. Store the key only in the deployment secret store. Do not commit it. For Vercel-style deployments, set `GOOGLE_APPLICATION_CREDENTIALS_JSON` to the full JSON key. For environments with a mounted secret file or workload identity, use Google's standard Application Default Credentials path and set `GOOGLE_APPLICATION_CREDENTIALS` when needed. `chat.bot` app auth does not require the extra one-time Workspace administrator approval that the newer `chat.app.*` scopes require. The Chat app still must be installed in a user's direct message before Atoll can deliver to that direct-message space. Google's app authentication docs: * [Authenticate as a Google Chat app](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) * [Verify requests from Google Chat](https://developers.google.com/workspace/chat/verify-requests-from-chat) ### 5. Configure the Marketplace SDK In Google Cloud Console, open **APIs & Services > Google Workspace Marketplace SDK > App Configuration**. Recommended starting configuration: * **App visibility:** Private for the Workspace domain while testing. Public requires Google review. * **Installation settings:** For Chat apps, use **Individual + Admin Install**. Workspace admins can still install the app for the domain, groups, or organizational units; domain policy can restrict whether individual users may install apps themselves. * **App integration:** Google Chat app. * **OAuth scopes:** include `https://www.googleapis.com/auth/chat.bot`. * **Developer information:** fill in the support/developer contact fields. Visibility is hard to change after saving, so choose private/unlisted for internal rollout unless you are ready for a public Marketplace review. ### 6. Create the Marketplace listing Open **APIs & Services > Google Workspace Marketplace SDK > Store Listing** and fill out: * App details and descriptions. * Icons, banner, and screenshots. * Terms, privacy, and support links. * Optional setup/admin configuration links pointing to this guide or your internal runbook. Private listings publish immediately after submission. Public listings go through Google's review process. If the listing includes a Chat app, Google also requires the Chat API app status to be live. Google's listing docs: * [Create a store listing](https://developers.google.com/workspace/marketplace/create-listing) ## Atoll deployment config Set these variables in the Atoll deployment: ```bash theme={null} NEXT_PUBLIC_APP_URL=https://atollhq.com GOOGLE_CHAT_CALLBACK_URL=https://atollhq.com/api/integrations/google-chat/events GOOGLE_CHAT_AUDIENCE=https://atollhq.com/api/integrations/google-chat/events GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account",...}' GOOGLE_CHAT_APP_URL=https://chat.google.com/ GOOGLE_CHAT_ADMIN_INSTALL_URL=https://workspace.google.com/marketplace/app/... GOOGLE_CHAT_MARKETPLACE_LISTING_URL=https://workspace.google.com/marketplace/app/... ``` `GOOGLE_CHAT_AUDIENCE` is optional when it matches `GOOGLE_CHAT_CALLBACK_URL`, but setting both makes the Google token verification behavior explicit. After setting the variables: 1. Deploy Atoll with the Google Chat migration applied. 2. Confirm the callback route is reachable: `POST /api/integrations/google-chat/events`. 3. Open **Settings > Members > Google Chat** as an Atoll owner/admin. 4. Confirm the Google Chat card appears with a **Find Atoll in Chat** button. ## Workspace admin setup 1. In Atoll, open **Settings > Members > Google Chat**. 2. Open the admin install link. 3. In Google Admin, choose **Everyone at your organization** or selected groups and organizational units. 4. Return to Atoll and send a test message from the Google Chat integration card. The admin install button appears when Atoll has either a `google_chat_installations.admin_install_url` row for the organization or a deployment-level `GOOGLE_CHAT_ADMIN_INSTALL_URL`. The **Find Atoll in Chat** button uses `GOOGLE_CHAT_APP_URL` when configured and otherwise opens Google Chat. Until Atoll has a dedicated Marketplace listing URL, users should click **New chat**, search for `Atoll`, and choose the app result. ## User setup Users can open **Settings > Profile > Notification preferences** and turn on **Google Chat mentions**. If the app is installed by the Workspace admin, Atoll sends enabled mention notifications to the user's direct message with the Atoll app. To link a direct message, users click **Find Atoll in Chat**, start a new chat with the Atoll app, generate a one-time setup message from Profile settings, copy it, and send it to the Atoll app in Google Chat. The setup message expires after 10 minutes and can only be used once. If Google Chat includes a verified email address in an event, Atoll can also use it as a fallback link signal. Recommended rollout copy: 1. Ask users to open **Settings > Profile > Notification preferences** in Atoll. 2. Turn on **Google Chat mentions**. 3. Click **Find Atoll in Chat**. 4. In Google Chat, click **New chat**, search for `Atoll`, and choose the app result. 5. Return to Atoll and click **Generate code** under **Connect Google Chat**. 6. Copy the setup message and send it to the Atoll app in Google Chat. 7. Return to Atoll or ask an admin to send a test message. Each user links their own direct message once. A Workspace admin can install the app for everyone, but Atoll still needs each user to send the one-time setup message so it knows which Google Chat direct message belongs to that Atoll member. ## Delivery behavior Atoll keeps in-app notifications as the source of truth. Google Chat delivery is a separate channel for mentions. Muting Google Chat mentions does not clear existing in-app notifications. Muting in-app mentions does not stop Google Chat mention delivery when Google Chat mentions remain enabled. ## API endpoints | Method | Endpoint | Description | | ------ | ------------------------------------------------------ | ---------------------------------------------------- | | `GET` | `/api/orgs/{id}/integrations/google-chat` | Read Google Chat integration status | | `POST` | `/api/orgs/{id}/integrations/google-chat/link-token` | Create a one-time user setup message | | `POST` | `/api/orgs/{id}/integrations/google-chat/test-message` | Send a Google Chat test message to the current admin | | `POST` | `/api/integrations/google-chat/events` | Receive Google Chat app events |