GSP250

Overview

Google Chat apps provide easy-to-use access points to your organization's data and services. Users can converse with apps within a chat experience. One way to create a Google Chat app is to use Google Apps Script. Apps Script also gives you easy access to other Google services like Drive, Gmail, Calendar, Docs, Sheets, and much more.

In this lab, you use Google Apps Script to create a simple Google Chat app with the converged Google Workspace Add-ons architecture.

What you'll learn

In this lab, you learn how to perform the following tasks:

• Create a Chat app from a template with pre-populated event handlers.
• Configure and publish the Google Chat app.
• Test the Google Chat app in Google Chat.

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources are made available to you.

This hands-on lab lets you do the lab activities in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

• Time to complete the lab—remember, once you start, you cannot pause a lab.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the right is the Lab setup and access panel with the following:

   • The Open Google Cloud console button
   • The temporary credentials (username and password) that you must use for this lab
   • Other information, if needed, to step through this lab

   Note that the lab timer is located near the top of the page, showing the remaining time.

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab setup and access panel.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab setup and access panel.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To access Google Cloud products and services, click the Navigation menu or type the service or product name in the Search field.

Task 1. Create a chat app from a template

To implement your Chat app, create a new Google Apps Script project using the Chat app template.

1. Click the Google Apps Script homepage link to open the Google Apps Script online editor.

2. Under Google Workspace add-on starters, click Chat app (Intermediate version).

3. Click Untitled project (the current name).

4. In the Edit project name dialog, rename the project to Friendly Bot, and then click Rename.

Google Workspace Add-ons event architecture for Google Chat

Google Chat apps built with Google Apps Script operate on the converged Google Workspace Add-ons (Chaddons) event-driven architecture. The interaction between the user, Google Chat, and the Google Workspace Add-on follows a structured flow:

1. User interaction: A user initiates an action, such as adding the Chat app to a space, starting a direct message (DM) with the app, @mentioning the app in a space, or removing the app from a space.
2. Event dispatch: Google Chat packages the interaction context into an event object with standardized ISO date-time timestamps (such as eventTime and message.createTime formatted in ISO 8601 UTC strings, for example 2026-08-06T14:30:00.000Z).
3. Event handler execution: Google Chat routes the event to the Google Workspace Add-on endpoint in Apps Script, invoking the corresponding event handler function.
4. Response delivery: The event handler processes the contextual event data and returns a synchronous or asynchronous response (text message or Card v2) to Google Chat.

Converged Google Workspace Add-on event handlers

In the converged Google Workspace Add-ons model, Google Chat dispatches interactions to specific event handler functions defined in your script:

• ADDED_TO_SPACE: Triggers when a user adds the Chat app to a space or starts a new direct message (DM). In Apps Script, you define the onAddedToSpace(event) function to return a greeting or onboarding card.
• REMOVED_FROM_SPACE: Triggers when a user removes the Chat app from a space or direct message. In Apps Script, you define the onRemovedFromSpace(event) function to perform cleanup logic. This handler does not post a response back to Google Chat.
• MESSAGE: Triggers when a user sends a message to the Chat app in a direct message or @mentions the app in a space. In Apps Script, you define the onMessage(event) function to parse the message payload and respond.
• CARD_CLICKED: Triggers when a user interacts with interactive UI widgets (such as buttons or form inputs) within a card message. In Apps Script, you define the onCardClick(event) function or custom action callbacks to handle user actions.

Standardized ISO date-time timestamps

In earlier legacy Chat bots, timestamps were delivered as Unix epoch milliseconds (such as event.eventTime.msSinceEpoch). In the converged Google Workspace Add-ons (Chaddons) event schema, all timestamps are standardized as ISO 8601 date-time strings (e.g., "2026-08-06T14:30:00.000Z"). This structure provides uniform timestamp formatting across Google Workspace Add-ons and the Google Chat API, accessible directly on properties such as event.eventTime and event.message.createTime.

Review the event handlers and code structure

The Chat app template pre-populates Code.gs with the event handler functions configured for the converged Google Workspace Add-on architecture.

1. In the Apps Script online editor, in the left navigation pane, click Code.gs to open the script file.

2. Review the pre-populated event handler functions:

   • onMessage(event): Handles the MESSAGE event when a user sends a message to the app. The function reads the user's message text and metadata from the event object, inspects the ISO date-time timestamp, and returns a formatted text reply.
   • onAddedToSpace(event): Handles the ADDED_TO_SPACE event when the app is added to a space or direct message, returning a greeting message.
   • onRemovedFromSpace(event): Handles the REMOVED_FROM_SPACE event when the app is removed from a space.

Task 2. Publish and test the Google Chat app

Before you can run and test the Chat app, the Google Chat API must be enabled for your Google Cloud project, and your Chat app must be published.

In this task, you complete the configuration steps to publish the Chat app: configure the OAuth consent screen, update the Apps Script application to reference your Google Cloud project, and configure the Google Chat API to publish the app for testing.

Configure the OAuth consent screen

1. In the Google Cloud console, click the Navigation menu () in the upper left, and navigate to APIs & Services > OAuth consent screen.

2. Click Get Started.

3. For Project configuration page, for App Information configure the following, and then click Next:

4. For Audience, select Internal and click Next.

5. For Contact Information, provide the email address , and then click Next.

6. Accept the policy, and click Continue. Then, click Create.

Click Check my progress to verify the objective.

Identify the Google Cloud project number and link Apps Script

1. From the Navigation menu (), click Cloud Overview > Dashboard.

2. In the dashboard, locate the Project Info section.

3. Record the Project number to use in the next step to configure your project.

4. Return to the Apps Script editor, and navigate to the Project Settings for the Friendly Bot project ().

5. Under Google Cloud Platform (GCP) Project, click Change project.

6. For GCP Project number, enter the project number that you copied earlier. Then, click Set project.

Configure and publish the Google Chat app

1. In the Apps Script editor, get the Head Deployment ID for the test deployment by clicking Deploy > Test deployments (top-right of the screen), and then clicking Copy next to Head Deployment ID.

2. In the Google Cloud console, navigate to Navigation menu () > APIs & Services > Library.

3. In the Library, search for Google Chat API, and select the API from the list of results.

The Google Chat API should already be enabled in this project. If it is not enabled, click Enable.

4. Click Manage then click on Configuration tab for the Google Chat API.

5. In the Configuration dialog, configure the fields with the following values:

6. Click Save.

7. After the changes are saved, scroll to the top of the Configuration dialog to update the App Status to LIVE – available to users.

You may have to refresh the page to see the App Status field. If the value for App Status is already set to LIVE – available to users, you can leave that value, but be sure to save the page again in the next step.

8. Click Save again.

Test the Google Chat app

Complete the following steps to test your app in Google Chat:

1. Click the Google Chat link to open Google Chat.

2. Select Start a chat (or click the plus icon next to Direct messages).

3. In the search box, enter Friendly Bot.

4. From the results, select Friendly Bot and click Install app for the installation app pop-up (Apps Script lab app) to start a direct message.

5. When the direct message thread opens, verify that you receive a greeting message from the Chat app thanking you for adding it to a direct message:

This response is initiated by the function named onAddedToSpace, which responds to the ADDED_TO_SPACE event when the app is added to a chat space or direct message.

6. In the message box, enter a message for the app, such as Hello app!, and press ENTER.

7. Verify that you receive a reply from the Chat app repeating your message, such as:

This response is initiated by the function named onMessage, which parses the MESSAGE event and ISO date-time timestamp when a user sends a message to the Chat app.

Congratulations!

You have successfully created, configured, and tested a Google Chat app using Google Apps Script with the converged Google Workspace Add-ons architecture!

Next steps / Learn more

• Check out what else you can do with Google Workspace:
  • Google Apps Script: Access Google Sheets, Maps & Gmail in 4 Lines of Code
• Check out these useful resources:
  • Google Chat API documentation
  • Build a Google Chat app with Google Apps Script
  • Overview of Google Chat apps
  • Publish Google Chat apps
  • Build interactive cards for Google Chat apps
  • Google Chat event formats and ISO timestamps
  • Google Workspace Add-ons for Google Chat
  • Google Workspace Learning Center

Google Cloud training and certification

...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.

Manual Last Updated August 7, 2026

Lab Last Tested August 7, 2026

Copyright 2026 Google LLC. All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.