How to create a Google Hangouts Chat Bot and setup a local development environment
A Google Apps Script Hangouts Bot tutorial to get data from an external api (https://numbersapi.com/) and setup a development environment with version control.
Chatbots, or “bots” for short, are computer programs that interact with people in a way that mimics human interaction to some degree. Bots in Hangouts Chat appear as special users marked as BOT. Just like people, bots can participate in chat rooms, and they can respond to direct message. But unlike people, bots only see messages directed to them when a person @mentions them in a chat room, or when a person sends them a direct message.
Introduction summarized from the Hangouts Chat API — Chatbot Concepts. To learn more, visit https://developers.google.com/hangouts/chat/concepts/bots.
Goals of the tutorial
This tutorial has the following goals:
- Create an Apps Script bot
- Setup a local development environment
- Connect the local environment to Github for version control
- Automatically push local changes to the Google Apps Script project on Google
- Code the bot to get data from the numbers api
- Deploy the chat bot for developer testing
This article presumes a basic understanding of the following technologies:
See the provided links per technology to refresh your working knowledge.
- git (Pro Git Book)
- GSuite (G Suite Learning Center)
- Google Apps Script (Google Apps Script Reference)
This article requires the following:
Login to G Suite
- Navigate to Google Drive
- Authenticate with your G Suite credentials
Create Google Apps Script File
Build web apps and automate tasks with Google Apps Script. Apps Script is a rapid application development platform that makes it fast and easy to create business applications that integrate with G Suite.
NOTE: See Google Apps Script for more information.
- Click Hangouts Chat Bot template to create a Google boilerplate template.
- Click File > Save, name the project ‘Numbers’, and click OK
- Open the Code.gs file, and locate the onMessage(event) function
- Replace this original text:
5. With the following:
6. So that the onMessage(event) function reads as follows:
7. Save the Numbers project, by executing the shortcut key stroke: Ctrl + s
Setup Local Environment
- Open a command line interface
- Create a new directory on your computer to store your project and navigate into the directory:
mkdir Numbers && cd Numbers
Install clasp and clone project
Develop Apps Script projects locally using clasp (Command Line Apps Script Projects). clasp allows you to check-in your code into source control, collaborate with other developers, and use your favorite tools to develop Apps Script.
NOTE: To learn more about clasp, see it’s github repository
- Download clasp:
sudo npm i @google/clasp -g
2. Enable the Apps Script API: https://script.google.com/home/usersettings
3. Login to clasp:
4. When prompted to login with a new window, Authenticate with your G Suite credentials.
5. Within the Google Apps Script editor, click File > Project properties and copy the Script ID to clipboard.
6. Using clasp, clone the Google Apps Script project with:
clasp clone <<script id from clipboard>>
Connect remote git repository
- Open a command line interface
- Navigate to the Numbers directory on your computer
- Execute the following command:
4. Create an account and/or sign in to github
5. Click on Repositories
6. Click on New to create a new repository
7. Enter a Numbers as the Repository name and click Create repository
8. Copy the first git command, located in the …or push an existing repository from command line, to clipboard.
9. Back in the Numbers directory, execute the copied command:
git remote add origin https://github.com/<<username>>/Numbers.git
10. To exclude the .clasp.json file from version control, execute:
echo '.clasp.json' >> ./.gitignore
11. To stage the files, execute:
git add .
12. To commit the files, execute:
git commit -am 'initial commit'
13. To push the files to github, execute:
git push -u origin master
Push changes to Apps Script Editor
- Prior to pushing changes to the Google Apps Script project, setup a .claspignore file. This file operates similarly to a .gitignore file. Create a file named, .claspignore with the following contents:
2. Execute the following command to push local code changes to the Google Apps Script project and editor:
Deploy the bot for Development testing
Step one: Get the Deployment ID
- Open the Numbers file in Google Apps Script
TIP | To find the Numbers script in your Google Drive, search for ‘type:script’ and Drive will display all of your Google Apps Script projects. Or, navigate to https://script.google.com to see all of your projects
2. Click on Publish > Deploy from manifest…
3. In the Deployments dialog , next to Latest Version (HEAD), click Get ID
4. Within the Deployment ID dialog box, copy Deployment ID value
NOTE | You will need this Deployment ID in step two below
5. Click Close and then click Close again to dismiss the dialog boxes
TIP | Use the HEAD deployment for development and simple unit testing. Bots using the HEADdeployment cannot be shared across a domain and require users to have access to your Google Apps Script.
NOTE | See https://developers.google.com/hangouts/chat/how-tos/manage-releases for more information about Managing releases of your bot
Step two: Configure the Hangouts Chat API on Google Cloud Console
- In the Script editor, click on Resources > Cloud Platform Project…
- Within the Cloud Platform project dialog box, click on the Cloud Platform project hyperlink that is associated with the project
NOTE | This step will open the Google Cloud Platform, offered by Google, is a suite of cloud computing services that runs on the same infrastructure that Google uses internally for its en-user products, such as Google Search and You Tube.
3. Within the Google Cloud Platform, enable the Hangouts Chat API by doing the following:
4. Click on the navigation menu and then click APIs & Services > Library
5. Start typing Hangouts Chat API, and then click on its associated Card
6. Within the API Library overview page, click on ENABLE
7. Once the API is enabled, click on Configuration
8. In the Configuration pane, configure the following:
9. Enter ‘Numbers’ in the Bot Name field
10. Enter ‘https://goo.gl/yKKjbw' in the Avatar URL field
11. Enter ‘Gets information about numbers’ in the Description field
12. Check mark the Bot works in direct messages checkbox withing the Functionality section
13. Select the Apps Script project radio button and paste the Deployment ID from Step One above
14. Select the Specific people and groups in your domain and enter your G Suite email address
15. Click SAVE
Step three: Test the setup
- Navigate to Hangouts Chat
- Click on Find people, rooms, bots
- Within the Add bot page, search for Numbers
- Select the Numbers bot
- Withing the direct message, type ‘Hello Numbers!’
- If everything is setup correctly, you should see:
Lint and watch for code changes
Before writing code that retrieves information about numbers from (https://numbersapi.com/), Let’s improve the quality and standardization of the code through linting.
NOTE | A linter or lint refers to tools that analyze source code to flag programming errors, bugs, stylistic errors, and suspicious constructs.
To learn more about the history of Linting, see Lint (Software) on wikipedia
NOTE | If not interested in setting up Linting, skip this step.
Setup ESLint within vsCode
NOTE | This step assumes the use of Visual Studio Code https://code.visualstudio.com/. Visit this link to download the code editor.
- Open the Numbers directory in vsCode
- Within vsCode, click View > Terminal
- Within Terminal execute the following:
sudo npm init
- Click enter to advance through the default selections
To learn more about npm see: https://docs.npmjs.com/cli/npm
2. Click on Extensions in the Activity Bar
3. In the Extensions panel, search for ESLint
4. Select ESLint provided by Dirk Baeumer
5. Within the Extension: ESLint informational page, click Install
6. Open the Command Palette and select ESLint: Create ESLint Configuration
TIP | ctrl + shift + p — also opens the Command Palette
7. This command launches eslint — init, provide the following answers to the init questions:
- How would you like to configure ESLint? Answer questions about your style
- Which version of ECMAScript do you use? ES5
- Where will your code run? Browser
- Do you use CommonJS? No
- Do you use JSX? No
- What style of indentation do you use? Spaces
- What quotes do you use for strings? Single
- What line endings do you use? Unix
- Do you require semicolons? Yes
- What format do you want your config file to be in? JSON
8. Upon success, the eslint — int will create a local .eslintrc.json file
Resolve ESLint problems with current code base
- With only the Code.js file open within vsCode, within the panel, click on PROBLEMS to see the current [eslint] problems
TIP | ctrl + j will toggle visibility of the panel
2. There will be approximately three types of lint problems listed, below is the summary and how to fix each type of lint error:
Setup watching to automatically push changes to Google
clasp provides the ability to have your development environment watch for changes in code and automatically push the changes to Google Apps Script project. And, since the Google Cloud Console Project is setup using the HEAD deployment, the changes will propagate to the live bot.
- Within Terminal, execute the following:
clasp push --watch
2. When successful, the terminal will show:
Pushed 2 Files
3. Within the Code.js file, make a simple change like adding the word this, within the onMessage function, at the end fo the “You just said this:” string
4. Save the Code.js file
5. Within the chat.google.com application, send the Numbers bot a direct message to see the clasp watch functionality publish the changes to Google and then automatically propagate the changes to the HEAD Deployment of the bot
Implement chat logic to call Numbers API
This part implements basic code to call the http://numbersapi.com for the user entered integer and then displays the trivia fact for the number in the Direct Message or Chat Room.
- With clasp watching changes to your local project, open Code.gs
- Replace the content of the file with the following:
Finally, within the chat.google.com application, send the Numbers bot a direct message containing your favorite integer to retrieve trivia about the number.