Checkpoints
Publish and test the bot
/ 30
Test the bot in card-formatted response
/ 30
Test the bot by button clicking on cards
/ 40
Google Chat Bot - Apps Script
GSP250
Overview
Google Chat bots provide easy-to-use access points to your organization's data and services. Users can converse with bots within a chat experience.
One way to create a Google Chat bot is to use Google Apps Script. This also gives you easy access to other Google services like Drive, Gmail, Calendar, Docs, Sheets, and much more.
In this lab, you will use Google Apps Script to create a simple Google Chat bot, which you'll name "Attendance Bot". The bot integrates with Gmail to set a user's vacation responder and integrates with Calendar to put a meeting on the user's calendar.
Objectives
What you'll learn
In this lab, you will learn how to perform the following tasks:
-
Add handlers in events raised in Google Chat.
-
Parse event objects sent from Google Chat.
-
Respond to Google Chat with card-formatted responses.
-
Define and react to custom actions for button clicks in cards.
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 will be made available to you.
This hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that 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
-
Click the Start Lab button. If you need to pay for the lab, a pop-up opens for you to select your payment method. On the left is the Lab Details panel with the following:
- The Open Google Console button
- Time remaining
- The temporary credentials that you must use for this lab
- Other information, if needed, to step through this lab
-
Click Open Google Console. 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. -
If necessary, copy the Username from the Lab Details panel and paste it into the Sign in dialog. Click Next.
-
Copy the Password from the Lab Details panel and paste it into the Welcome dialog. Click Next.
Important: You must use the credentials from the left panel. Do not use your Google Cloud Skills Boost credentials. Note: Using your own Google Cloud account for this lab may incur extra charges. -
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 Cloud Console opens in this tab.
Task 1. Create handlers for Google Chat events
To implement your bot, create a new Google Apps Script project.
-
Click the Google Apps Script editor link to open the Google Apps Script online editor.
-
Click Untitled project (the current name).
-
In the Edit project name dialog, rename the project to
Attendance Bot
, and then click Rename.
Events in Google Chat
Most Apps Script bot interactions with Google Chat are event-driven. The interaction between the user, the bot, and Google Chat typically follows a sequence.
- A user initiates an action, like adding a bot to a room, starting a direct message (DM) with a bot, or removing the bot from a room.
- The action raises an event aimed at the bot in Google Chat.
- Google Chat calls the corresponding event handler defined in the bot's script.
Google Chat raises four events that your Apps Script bot can listen for:
-
ADDED_TO_SPACE
: This event occurs when a human user adds a bot to a room or a DM. In Apps Script, you define anonAddToSpace()
function to handle this event. -
REMOVED_FROM_SPACE
: This event occurs when a user removes the bot from a room or DM. This event does not post a response back to Google Chat. In Apps Script, you define anonRemoveFromSpace()
function to handle this event. -
MESSAGE
: This event occurs when a user messages the bot, either directly in a DM or as an @mention in a room. In Apps Script, you define anonMessage()
function to respond to this event. -
CARD_CLICKED
: This event occurs when the user clicks a button with a custom action assigned to it. In Apps Script, you define anonCardClick()
function to respond to this event.
- To define the handlers for the
ADDED_TO_SPACE
andREMOVE_FROM_SPACE
events, replace the contents of theCode.gs
file with the following code. (You add handlers for theMESSAGE
andCARD_CLICKED
events later in this lab.)
Code.gs
-
Click the Save project button (
) in the top action bar to save the file.
Task 2. Publish the bot
Before you can run and test the bot, the Google Chat API must be enabled for your Google Cloud project, and your bot must be published to Google Chat. To do this, you:
-
Update the manifest file.
-
Enable the and configure the Google Chat bot.
Update the manifest file
The Apps Script editor hides manifest files by default to protect Apps Script project settings. So you need to make the manifest files visible.
- In the left panel, click Project Settings (
).
- Check Show "appsscript.json" manifest file in editor in the General settings section.
If you go back to the Editor (), the
appsscript.json
file should now be available.
- Edit the
appsscript.json
file. Under the line:"exceptionLogging": "STACKDRIVER"
, add the new line:
Your manifest file should look similar to the following example:
appsscript.json
-
Click Save to save the (
)
appsscript.json
project.
Configure the Google Cloud project and update the script to use it
-
Go to the Google Cloud Console, click the Navigation menu (
) in the upper left and navigate to APIs & Services > OAuth consent screen.
-
Set User Type to Internal and click Create.
-
On the next page, (the OAuth consent screen), configure the following:
Field | Value |
---|---|
App name | Attendance Bot |
User support email | Select the email ID |
Developer contact information |
- Click Save and Continue.
- On the next page (Scopes), leave all the fields empty, and then click Save and Continue.
As shown in the next page (Summary), the OAuth Consent Screen is now created for your app.
-
Click Back to Dashboard at the bottom of the page.
-
Click the More icon (
) in the upper right to expand the menu and select Project settings.
-
Record the Project number to use in the next step to configure your project.
-
In the App Script editor, navigate to the Project Settings (
).
-
Under Google Cloud Platform (GCP) Project, click Change project.
-
When prompted, enter the Project number value, copied earlier, in the GCP Project number field. Then click Set project.
Configure and publish the chat bot
- Go to the Apps Script editor and get the deployment ID. You do this by clicking on Deploy > New Deployment in the top-right of the screen.
- In the Description field, enter
App Script lab bot
, and click Deploy. - Note down the Deployment ID to use later and click Done.
- Go to the Cloud Console, navigate to Navigation Menu (
) > APIs & Services > Library.
- In the Library, search for
Google Chat API
. Select the API from the list of results. - By default, the Google Chat API is already enabled. If it is not enabled, click Enable.
- Click Manage and then click the Configuration tab under the Google Chat API section.
- In the Configuration dialog, set the fields with the following values:
Field | Value |
---|---|
App name | Attendance Bot |
Avatar URL | https://goo.gl/kv2ENA |
Description | Apps Script lab bot |
Functionality | Receive 1:1 messages |
Connection settings | Check Apps Script project, and then paste your script's Deployment ID into the Deployment ID field |
Visibility | Enter |
-
Click SAVE.
-
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 reload the browser page to see the App Status field. -
Click SAVE again.
Test the bot
To test your bot in Google Chat, do the following:
- Click the Google Chat link to open Google Chat.
- Select Start a chat (
) > Find apps in the Chat section.
- From the list, select the "Attendance Bot, Apps Script lab bot" that you created, and click Chat.
When the direct message thread opens, you should see a message from the bot thanking you for adding it to a DM.
Click Check my progress to verify the objective.
Task 3. Define a card-formatted response
In the previous step, your bot responded to Google Chat events with a simple text response. In this step, you update your bot to respond with cards.
Card responses
Google Chat supports the use of cards for responses. Cards are visual containers that allow you to group sets of user interface widgets together. Cards can display headers, text paragraphs, sets of buttons, images, and key/value text. Your bot can define one or many cards in its JSON response to Google Chat, which then translates your response into the corresponding UI elements.
The following image shows a card response with three sections that includes a header, a key/value widget, an image widget, and a text button.
-
To respond to user messages with a card response, in Apps Script > Editor (
), add the following code to your bot's
Code.gs
file:
Code.gs
-
Click the Save button (
) to save the
Code.gs
file.
- The
onMessage()
function, added in this step, reads the user's original message and constructs a response as a simple TextParagragh widget. - The
onMessage()
function then callscreateCardResponse()
, which places the TextParagraph widget within a section of a single card. - The bot returns the JavaScript object constructed with the card response to Google Chat.
You need to save this version of the script.
-
Click Deploy > Manage deployments in the top-right of the screen.
-
Click on the Edit icon (
) associated with your deployment, and select New version from the Version drop-down.
-
Click Deploy to save the version. This updates the deployment to use the new version of the script.
-
Click Done.
Test the bot
- To retest this bot, simply go back to your direct message with the bot in Google Chat and type a message (any message will do).
The Attendance bot will respond with a Log your vacation time card.
onMessage()
event handler parses the event object passed to it by Google Chat to extract the user's original message. You can also get other types of information about the event, including the name of the user that initiated the event, their email address, the name of the room that the event occurred in, and much more.For more information about the structure of the event objects sent by Google Chat, you can refer to the Event formats reference guide.
Click Check my progress to verify the objective.
Task 4. React to button clicks in cards
In the previous step, your bot responded to a message from a user—a MESSAGE
event—with a simple card that contained a TextParagragh widget. In this step, you will create a response that includes buttons, where each button has a custom action defined for it.
Interactive cards
Card responses can contain one of two types of buttons: TextButton widgets, which display text-only buttons; and ImageButton widgets, which display a button with a simple icon or image without text.
Both TextButton and ImageButton widgets support one of two onClick
behaviors (as defined in the JSON response sent back to Google Chat): either openLink
or action
. As the name implies, openLink
opens a specified link in a new browser tab.
The action
object, however, specifies a custom action for the button to perform. You can specify several arbitrary values in the action object, including a unique actionMethodName
and a set of key / value parameter pairs.
Specifying an action
object for the button creates an interactive card. When the user clicks the button in the message, Google Chat raises a CARD_CLICKED
event and sends a request back to the bot that sent the original message. The bot then needs to handle the event raised from Google Chat and return a response back to the space.
-
Return to the Apps Script > Editor(
).
-
In
Code.gs
, replace theonMessage()
function with the following code. This code creates two buttons, a Set vacation in Gmail and a Block out day in Calendar button in the card sent to Google Chat.
Code.gs
Are you taking time off today?' } }, { buttons: [{ textButton: { text: 'Set vacation in Gmail', onClick: { action: { actionMethodName: 'turnOnAutoResponder', parameters: [{ key: 'reason', value: reason }] } } } }, { textButton: { text: 'Block out day in Calendar', onClick: { action: { actionMethodName: 'blockOutCalendar', parameters: [{ key: 'reason', value: reason }] } } } }] }]; return createCardResponse(widgets); }
-
To handle the
CARD_CLICKED
event, you need to add theonCardClick()
function to your bot's script (in this case, theonCardClick()
function forCode.gs
).
Code.gs
In responding to user clicks, now the bot does one of two things: It sets the user's vacation responder in Gmail to an "out of office" message; or it schedules an all-day meeting on the user's Calendar. To accomplish these tasks, the bot calls the Gmail advanced service and the Calendar Apps Script API.
-
Add the following code to your script to integrate the bot with Gmail and Calendar:
Code.gs
Created by Attendance Bot!", restrictToContacts: true, restrictToDomain: true, startTime: currentTime, endTime: currentTime + ONE_DAY_MILLIS }, 'me'); } /** * Places an all-day meeting on the user's Calendar. * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER */ function blockOutCalendar(reason) { CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS)); }
- Click the Save button (
) to save the
Code.gs
file. - On the Services tab, click Add a service (
) and select Gmail API from the list.
- Click Add.
Next, you update your project with this version of script.
- Select Deploy > Manage deployments in the top-right corner.
- Click the Edit icon (
) of your deployment and select New version from the Version drop-down menu.
- Click Deploy to save the version. This updates the deployment to use the new version of the script.
- Click Done.
Finally, you need to check to be sure the Gmail Advanced Service is enabled in this project. To enable the Gmail API, do the following:
-
In the Google Cloud Console, navigate to Navigation Menu (
) and select > APIs & Services > Library.
-
In the Library, search for
Gmail API
. Select the API from the list of results. -
The Gmail API is already enabled for you. If it is not, click Enable.
Test the bot
- To test this version of your bot, open the DM that you started in previous steps in Google Chat and type
I'm sick
. The bot should respond with a card similar to the image below.
- To configure the Attendance Bot, click Configure, choose your user account, click ALLOW, and then close the page when you see the message "You may close this page now".
Now the bot displays the available options.
-
Click SET VACATION IN GMAIL. You should see the message "Turned on vacation settings."
-
Click BLOCK OUT DAY IN CALENDAR. You should see the message "Blocked out your calendar for the day."
- Click the Google Apps icon to access and check the Gmail and Calendar associated with this account.
You should see the Vacation Setting in Gmail.
You should also see a day blocked out in the Calendar.
Click Check my progress to verify the objective.
Congratulations!
You created a bot that responds to user messages, sets their vacation responder in Gmail, and puts an all-day event on their Calendar.
Finish your quest
This self-paced lab is part of the Workspace Integrations quest. A quest is a series of related labs that form a learning path. Completing this quest earns you a badge to recognize your achievement. You can make your badge or badges public and link to them in your online resume or social media account. Enroll in this quest and get immediate completion credit. Refer to the Google Cloud Skills Boost catalog for all available quests.
Take your next lab
Check out what else you can do with Workspace:
Learn more
- Google Chat documentation site
- Apps Script bot quickstart
- Create new bots
- Publish bots
- Create interactive cards
- Cards reference
- Event object reference
- Gmail advanced service reference
- Calendar Apps Script API reference
- Google Workspace Learning Center
Manual Last Updated February 22, 2023
Lab Last Tested February 22, 2023
Copyright 2023 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.