Google Chat

Google Chat is Google Workspace's messaging service for direct messages, group conversations and spaces, with support for Chat apps, interactive cards and attachments. The UnifyApps Google Chat connector uses the Google Chat API to create and manage spaces and memberships, send, read and delete messages, send card messages, download attachments and react when your Chat app receives a message or is added to a space, from workflows and agents.

This guide covers every authentication type available on the connection form, and the actions and triggers supported, along with the Google Chat scope each one needs.

Authentication

Before you begin, you should have the following information:

• Connection name: a descriptive name such as MyAppGoogleChatIntegration, so the connection is easy to identify later.

• Authentication type: select the type of authentication for connecting to your Google Chat account:

  1. OAuth

  2. OAuth with Client Credentials

  3. Service Account

OAuth has no Scopes field and always requests chat.messages, chat.messages.readonly, chat.messages.create, chat.spaces, chat.spaces.readonly, chat.spaces.create, chat.memberships, chat.memberships.readonly, chat.memberships.app and chat.delete. OAuth with Client Credentials has a Scopes field with the same ten scopes selected by default. Service Account has an optional Scopes field that defaults to chat.app.messages, chat.app.memberships, chat.app.spaces.create, chat.bot, chat.messages, chat.spaces, chat.delete and chat.memberships. See the Scopes Required column in the tables below.

1. OAuth

Use this when you want to connect with your own Google account and do not need to create a Google Cloud app.

1. Enter a Connection name.

2. Select OAuth as the Authentication type.

3. Click Authorize. You are redirected to the Google sign-in page.

4. Sign in with the Google account the connection should act as in Google Chat.

5. Review the permissions on the consent screen and click Allow.

6. You are redirected back to UnifyApps with a confirmation that the account is connected.

2. OAuth with Client Credentials

Use this when your organization wants the connection to use its own Google Cloud OAuth client, while actions still run as the Google user who signs in.

Step 1: Create an OAuth client in Google Cloud

1. In the Google Cloud Console, select or create a project, and enable the Google Chat API under APIs & Services → Library.

2. Open the Google Chat API's Configuration page, enter an App name, Avatar URL and Description under Application info, and click Save. Google Chat API calls need a configured Chat app in the project.

3. Go to Google Auth platform → Branding. If you see Google Auth platform not configured yet, click Get Started, enter an App name, User support email, Audience and contact email, and click Create.

4. Go to Data Access, click Add or Remove Scopes, select the Google Chat scopes the connection will use, and click Save. If the audience is External, add the users who will sign in under Audience → Test users.

5. Go to Google Auth platform → Clients and click Create Client. Choose Web application as the Application type and enter a name.

6. Under Authorized redirect URIs, click Add URI and paste the Callback URL shown on the UnifyApps connection form (it is copyable and differs per environment).

7. Click Create, then copy the Client ID and Client secret. Copy the secret immediately: Google shows it only once.

Step 2: Connection setup in UnifyApps

1. Open Connections → New Connection → Google Chat and enter a Connection name.

2. Select OAuth with Client Credentials as the Authentication type.

3. Enter the Client ID and Client Secret copied from Google Cloud.

4. Keep the default Scopes, or select the same scopes you added to the consent screen.

5. Click Authorize, sign in with Google and click Allow on the consent screen.

6. Confirm the success message after the redirect back to UnifyApps.

3. Service Account

Use this for Google Workspace domains, where a service account acts on behalf of a user in the domain through domain-wide delegation. No user has to sign in.

Step 1: Create a service account in Google Cloud

1. In the Google Cloud Console, select or create a project, enable the Google Chat API under APIs & Services → Library, and fill in the Application info on the Google Chat API's Configuration page.

2. Go to IAM & Admin → Service Accounts and click Create service account. Enter a name and click Done.

3. Open the service account and copy its Email. Click Show advanced settings and, under Domain-wide delegation, copy the Client ID used in the next step.

4. Go to the Keys tab → Add key → Create new key, choose JSON and click Create. The downloaded file holds the client_email and private_key. Store it securely.

Step 2: Give the service account domain-wide access

1. A Google Workspace super administrator opens the Admin console → Security → Access and data control → API controls.

2. Click Manage Domain Wide Delegation → Add new.

3. Enter the service account's client ID, add the OAuth scopes the connection will request (for example https://www.googleapis.com/auth/chat.messages, https://www.googleapis.com/auth/chat.spaces, https://www.googleapis.com/auth/chat.memberships and https://www.googleapis.com/auth/chat.delete), separated by commas, and click Authorize. See Delegate domain-wide authority to your service account for details.

Note: every scope selected in the UnifyApps Scopes field must also be authorized here, or Google refuses to issue a token. Because this type always acts as the User email, select only user scopes such as chat.messages, chat.spaces, chat.memberships and chat.delete. Google does not allow the chat.bot and chat.app.* scopes in the default list with domain-wide delegation; they are for a Chat app authenticating as itself. Google says changes can take up to 24 hours to apply.

Step 3: Create the connection in UnifyApps

1. Select Service Account as the Authentication type.

2. Enter the GCP Project Service Account Email and paste the Private Key from the JSON key file.

3. Enter the User email of the Workspace user the connection acts as.

4. In Scopes, clear the default chat.bot and chat.app.* scopes and keep the scopes granted in Step 2.

5. Click Create. Google Chat has no connection test, so the credentials are first checked when an action runs.

Actions

Scopes are shown in short form: chat.messages means https://www.googleapis.com/auth/chat.messages. Any broader scope also works.

Triggers

Both triggers receive events from your Chat app over HTTP, so they need no scope. Copy the Webhook URL shown in the trigger, then in the Google Cloud Console open the Google Chat API's Configuration page. Under Interactive features, turn them on and select Join spaces and group conversations. Under Connection settings, select HTTP endpoint URL, then under Triggers select Use a common HTTP endpoint URL for all triggers, paste the webhook URL and click Save.