How to create a Google Hangouts Chat Bot and setup a local development environment

8 min readJan 31, 2019

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.

Introduction

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

Prerequisites

This article presumes a basic understanding of the following technologies:

See the provided links per technology to refresh your working knowledge.

JavaScript (Watch and Code — Practical JavaScript)
git (Pro Git Book)
GSuite (G Suite Learning Center)
Google Apps Script (Google Apps Script Reference)

This article requires the following:

A GSuite account (see G Suite FAQs for more details)
Access to the Google Cloud Platform (https://console.cloud.google.com)

Setup

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:

clasp login

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:

git init

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:

**/**
!Code.js
!appsscript.json

2. Execute the following command to push local code changes to the Google Apps Script project and editor:

clasp push

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

NOTE | npm is the package manager for the Node Javascript platform. It puts modules in place so that node can find them, and manages dependency conflicts intelligently.
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:

Pushing files...
    --Code.js
    --appsscript.json
    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.

My Github: https://github.com/daubejb
My Twitter: https://twitter.com/jeffdaube
My Website: https://jeffdaube.com
My LinkedIn: https://www.linkedin.com/in/jeffreydaube/