Google Chat

​

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_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

​

1. Prepare URLs and assets

​

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.

• Configure the Google Chat API
• Configure your app in the Google Workspace Marketplace SDK

​

3. Configure the Chat API

• 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.

• 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:

• Do not add commands in the Commands section for this version. Atoll links users by parsing a normal direct message that starts with connect <token>, 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.

​

4. Create app credentials

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.

• Authenticate as a Google Chat app
• Verify requests from Google Chat

​

5. Configure the Marketplace SDK

• 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.

​

6. Create the Marketplace listing

• 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.

• Create a store listing

​

Atoll deployment config

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_ADMIN_INSTALL_URL=https://workspace.google.com/marketplace/app/...
GOOGLE_CHAT_MARKETPLACE_LISTING_URL=https://workspace.google.com/marketplace/app/...

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 > Integrations > Google Chat as an Atoll owner/admin.
4. Confirm the install link appears.

​

Workspace admin setup

1. In Atoll, open Settings > Integrations > 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.

​

User setup

1. Ask users to open Settings > Profile > Notification preferences in Atoll.
2. Turn on Google Chat mentions.
3. Click Generate under Connect Google Chat.
4. Copy the connect <token> command.
5. Open a direct message with the Atoll app in Google Chat and send the command.
6. Return to Atoll or ask an admin to send a test message.

​

Delivery behavior

​

API endpoints