Google Chat

Google Chat is a messaging platform that allows you to communicate with your users. You can share files, images, videos, and audio and have conversations.

Setup Google chat using Google console developer portal

Login to the Google console portal to setup your Google Chat.

To setup Googel chat to your bot, configure the following:

1. Create a new project on the Google Console
2. Enable the service account and Generate keys
3. Enable the Google Chat API
4. Configure your Google chat bot

Step 1: Create a new project on Google console

To create a new project on Google console, follow these steps:

1. On the Google console developer portal, click Go to create a project.

2. Enter the Project name, Organization, and Location, then click Create to create a project.

   

3. Your project will be successfully created.

   

Step 2: Enable Service account and Generate Keys

To enable service account and generate keys, follow these steps:

1. On the navigation panel, go to IAM & Admin > Service Accounts.

   

2. Click on + CREATE SERVICE ACCOUNT.

   

3. Add the Service Account Details such as Service account name, Service account ID, and Service account description, then CREATE AND CONTINUE in Step 1. Skip Step 2 and 3.

   

• The service account details for your project will be added successfully.

  

5. Once the service account is created, click on the email link.

   

6. Go to KEYS tab and click on ADD KEY > Create new key.

   

7. Select the Key type as JSON and click Create.

note

• Ensure that you save this file carefully, it cannot be recovered once lost.

• A confirmation message Private key saved to your computer is displayed.

Step 3: Enable Google chat API

To enable the Google chat API, follow these steps:

1. On the navigation panel, click APIs & Services.

   

2. Click + Enable APIs and services.

   

3. In the Search bar, search for "Google Chat API" and select it.

   

4. Click Enable. The Google Chat API will be enabled.

   

5. Once the Google Chat API is enabled, you need to configure your Google Chat bot as explained in the following.

Step 4: Configure your Google chat bot

To configure your Google chat Bot, follow these steps:

1. Go to Configuration, and enter the following details to configure your Google Chat Bot:

   • Enter the name of your app.
   • Add the avatar URL.
   • Enter the relevant description based on your app.
   • Enable the Interactive features.
   • Under Functionality, select both checkboxes.
   • Under Connection settings, select App URL and enter https://cloud.yellow.ai/integrations/googleChat/receive/[BOT ID]

note

Based on the region of your bot, which is r1/r2/r3/r4/r5, you need to append that to the domain of the webhook URL. For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to the Indian region, you can use the origin domain itself.

• Under Visibility, enter the email addresses to add individuals and groups to your domain.

• Click Save to save the configuration details.

  

Connect Google chat to your bot

Prerequisite

• Copy the Client Email and Private Key from the JSON file that you downloaded earlier.

  

To connect the Google chat channel to your bot on the platform, follow these steps:

1. On the left navigation bar, click Extensions.

   

2. Click Channels > Messaging > Google chat.

   

3. Enter the Client email and Private key that you have copied from the downloaded JSON and click Save.

   

   • Your Google chat channel will be successfully connected.

4. Navigate to the Overview page, under the Active channels section, to verify that the Google chat channel is successfully connected to your bot.

Add events to your bot

To add events to your bot, follow these steps:

1. On the left navigation bar, click Harness, then under Automation, click Scheduler > Custom events.

   

2. Click + Add event.

   

3. Add the following events:

   • google_chat_added_to_space: This event is received when your Bot is added to a space.
   • google_chat_removed_from_space: This event is received when your Bot is removed from a space.

4. Enter the Event name and Event description, then click Create event.

   

5. The events will be successfully added.

   

   

Test your bot on Google chat

After connecting your bot to the Google chat, you can test your bot.

Prerequisites

• Ensure that you have created the bot with intents and configured the flows with the same intent. For more information, click here.

To test your bot on Google chat, follow these steps:

1. Login to your personal email account and click Chat > New Chat > Find apps.

   

2. In the Search bar, search for the name of the app that you have created.

   

3. Select the app and click Chat.

   

4. Start the conversation to test your bot.

   

Receive emoji reactions

When a user reacts with an emoji to a message from your Chat app in a Google Chat space or group chat, your AI agent receives the reaction as an event. Use the event to start a flow, for example to thank the user for a 👍 or to record quick feedback.

Google doesn't send reactions to the app URL from Step 4. It publishes them through the Google Workspace Events API to a Pub/Sub topic in your Google Cloud project, and a Pub/Sub push subscription forwards them to your AI agent. You set this up once, then turn on Reaction events for the channel.

note

• Reactions arrive from spaces and group chats that your Chat app is a member of. Reactions in 1:1 direct messages with the app arrive too once you set up domain-wide delegation.
• Only reactions to your Chat app's own messages reach your AI agent. Reactions to messages between people are ignored.

Prerequisites

• The Google Chat channel is connected. See Connect Google chat to your bot.
• Billing is enabled for the Google Cloud project. Pub/Sub needs it.
• A super admin of your Google Workspace can approve the app, and set up domain-wide delegation if you want reactions in direct messages.

To receive reactions, complete these steps in order:

1. Set the authentication audience of your Chat app
2. Enable the APIs
3. Create a Pub/Sub topic
4. Create a push subscription
5. Approve the app in Google Workspace
6. Receive reactions in direct messages (optional)
7. Turn on reaction events
8. Use the reaction events in a flow

Set the authentication audience of your Chat app

Your AI agent starts and renews reaction tracking only for messages that Google Chat signs for your app URL. Google Chat signs them that way only when the Chat app's authentication audience is its HTTP endpoint URL.

1. In the Google Cloud console, go to APIs & Services > Enabled APIs & services > Google Chat API > Configuration.
2. Under Connection settings, check that HTTP endpoint URL is your app URL from Step 4.
3. In Authentication Audience, select HTTP endpoint URL, then click Save.

Enable the APIs

In the Google Cloud project of your Chat app, go to APIs & Services > + Enable APIs and services. Search for each of these APIs and click Enable:

• Google Workspace Events API
• Cloud Pub/Sub API
• Google Workspace Marketplace SDK

Create a Pub/Sub topic

Google Chat publishes the reactions to this topic. Create it in the same project as your Chat app, because Google doesn't accept a topic from another project.

1. In the Google Cloud console, search for Pub/Sub, and under Top results, click Pub/Sub.

   

2. Click Topics, then click Create topic.

   

3. Enter a Topic ID, for example gchat-reactions. Clear Add a default subscription, then click Create.

4. Copy the topic name from the topic page, for example projects/my-project/topics/gchat-reactions. You need it to turn on reaction events.

5. On the topic page, open the Permissions tab of the info panel (click Show info panel if it's hidden), and click Add principal.

6. In New principals, enter [email protected]. In Role, select Pub/Sub Publisher, then click Save.

note

If Save fails with an organization policy error, your organization limits which domains can be given access (the Domain restricted sharing policy). Ask your Google Cloud administrator to allow [email protected] in this project.

Create a push subscription

The push subscription forwards each event from the topic to your AI agent.

1. On the topic page, click Create subscription.
2. Enter a Subscription ID, for example gchat-reactions-push.
3. In Delivery type, select Push. In Endpoint URL, enter https://cloud.yellow.ai/integrations/googleChat/events/[BOT ID].
4. Select Enable authentication. In Service account, select the service account whose Client email you used to connect the channel. Leave Audience empty.
5. Leave Enable payload unwrapping cleared.
6. In Expiration period, select Never expire. In Retry policy, select Retry after exponential backoff delay.
7. Keep the other defaults and click Create.

The subscription then appears in Pub/Sub > Subscriptions, with the delivery type Push.

caution

The endpoint URL ends in /googleChat/events/[BOT ID], not in the /googleChat/receive/[BOT ID] of your app URL. Use the same domain and the same [BOT ID] as your app URL. With the /receive/ URL, Pub/Sub reports every push as delivered, but your AI agent never sees the reactions.

note

• Use the same regional domain as the app URL in Step 4. For example, for an AI agent in r1, the endpoint URL starts with https://r1.cloud.yellow.ai.
• Your AI agent accepts an event only when the push is signed by the service account of the channel's Client email and is sent to its own URL. Any other push is rejected.
• If your Google Cloud project was created before April 8, 2021, also grant service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com the Service Account Token Creator role on that service account.

Approve the app in Google Workspace

Reading reactions in spaces needs a one-time approval of your Chat app by a Google Workspace admin. Google takes the approval through a private Google Workspace Marketplace listing, which only your organization can see.

1. Go to IAM & Admin > Service Accounts and open the service account of the channel. Expand Advanced settings, click Create Google Workspace Marketplace-compatible OAuth client, then click Continue. If Google asks you to configure the OAuth consent screen first, choose Internal as the user type.
2. Go to APIs & Services > Google Workspace Marketplace SDK > App Configuration, set the following, and click Save:
   • App visibility: Private
   • Installation settings: Individual + Admin install
   • App integrations: Chat app
   • OAuth scopes: https://www.googleapis.com/auth/chat.bot and https://www.googleapis.com/auth/chat.app.messages.readonly
   • Developer information: your name, website, and email
3. Open Store Listing and fill in the required details, then click Publish. Google doesn't review a private app, so it's available to your organization right away. The listing needs:
   • App icons of 32 × 32 and 128 × 128 pixels, and a card banner of 220 × 140 pixels
   • At least one screenshot of 1280 × 800 pixels
   • The regions of your users in Distribution
   • Links to your terms of service, privacy policy, and support page
4. A super admin of your Google Workspace signs in to the Google Workspace Marketplace, opens your app, and clicks Admin install (not Install). They select Everyone at your organization and finish the steps. The approval can take up to 24 hours to apply.

caution

• An admin install adds the app to the Google Chat of every user in your organization, and users can't remove it.
• Your AI agent receives the google_chat_added_to_space event once for each of these users. If a flow replies to that event, every user in your organization receives the reply.

Receive reactions in direct messages

This step is optional. Without it, your AI agent receives reactions only in spaces and group chats.

In a 1:1 direct message, Google accepts a reaction subscription only when it's made on the user's behalf. Your AI agent makes one for each user automatically, through domain-wide delegation: a super admin of your Google Workspace allows the channel's service account to read reactions for users.

1. In the Google Cloud console, go to IAM & Admin > Service Accounts, open the service account of the channel, and copy its Unique ID. This is the client ID that the admin authorizes.
2. A super admin of your Google Workspace signs in to the Google Admin console and goes to Security > Access and data control > API controls > Manage Domain Wide Delegation.
3. Click Add new and enter:
   • Client ID: the Unique ID from step 1
   • OAuth scopes: https://www.googleapis.com/auth/chat.messages.reactions.readonly
4. Click Authorize. The change usually applies within minutes, and can take up to 24 hours.

If the console shows Client ID already exists, the service account already has an entry. Click Cancel, open that entry in the list, and add the scope to it. Don't overwrite the entry, because overwriting replaces all of its scopes.

After that, a user's direct message with the app starts receiving reactions from the user's next message to the app.

caution

• Domain-wide delegation lets the service account read the emoji reactions of any user in your Google Workspace. Your AI agent uses it only for each user's direct message with your Chat app. Keep the service account key secure.
• To stop, delete the entry in Manage Domain Wide Delegation. Direct messages then stop receiving reactions. Spaces and group chats aren't affected.

note

Reactions in direct messages are received only for users of your own Google Workspace, not for external users.

Turn on reaction events

1. On the left navigation bar, click Extensions, then click Channels > Messaging > Google chat.
2. If the channel is already connected, click Details on the connected account. You don't need to disconnect the channel. The form opens with your Client email and Private key already filled in.
3. Turn on Reaction events.
4. In Pub/Sub topic, enter the topic name that you copied, in the form projects/<project-id>/topics/<topic-id>.
5. Click Save.

Saving the channel adds these events to your AI agent. To see them, click Harness on the left navigation bar, then under Automation, click Scheduler > Custom events:

• google_chat_reaction_added: a user added an emoji reaction to a message from your Chat app.
• google_chat_reaction_removed: a user removed that reaction.

Use the reaction events in a flow

Start a flow with the google_chat_reaction_added event, or with google_chat_reaction_removed to respond to a removal. Replies from the flow go to the same space and thread as the message that got the reaction.

The flow reads the reaction from {{data.event.data.<field>}}:

Field	Value
emoji	The emoji, for example 👍. For a custom emoji, its name.
emojiType	unicode, or custom for a custom emoji.
userId	The Google Chat user ID of the person who reacted.
spaceId	The ID of the space, group chat, or direct message.
messageId	The Google Chat ID of the message that got the reaction.
messageText	The text of that message.
ymMessageId	The Yellow.ai ID of that message, when available.
eventTime	The time of the reaction.

For example, a message node with the text Thanks for the {{data.event.data.emoji}} thanks the user with the emoji they chose.

Test reaction events

1. In Google Chat, add your Chat app to a space, or open a space that already has it.
2. Send a message that mentions the app, for example @<app name> hi, and wait for the reply.
3. React to the reply with an emoji. The flow that starts with google_chat_reaction_added runs.

To test a direct message, open your direct message with the app, send a message, wait for the reply, and react to it.

note

• Wait 2 minutes after you save the channel before you test.
• Your AI agent starts receiving a space's reactions when the app is added to the space, or when someone messages the app there after you turn on Reaction events. A direct message starts with the user's first message to the app after delegation applies. Reactions made before that aren't received.

View reaction analytics

Each reaction is also recorded as a custom analytics event named message-reaction.

1. Go to Insights > Data Explorer.
2. Under Custom tables, open analytics.
3. Filter event by message-reaction.

Each row shows whether the reaction was added or removed, the emoji, the user, the message that got the reaction, the space, the session, and the journey and step that sent the message.

note

The analytics table appears once your AI agent records its first custom analytics event.