How to develop a serverless chatbot (for Hangouts Chat) — Intro & Architecture
Visit http://www.mikenikles.com for my latest blog posts.
Introduction
This post is part of a series where you can learn how to develop, monitor (and later debug and profile) a serverless chatbot (for Hangouts Chat). Please refer to the other posts linked below for context.
- Intro & architecture (this post)
- Process incoming chat messages
- Send messages to users
- Find reminders & notify users
- Monitoring
A few months ago, I started to use a Pixelbook. Since then, I’ve also used Google’s G Suite collaboration & productivity apps extensively, including Hangouts Chat. At the time of writing, there is no native reminder feature and I decided to build a Reminder Bot. This series of blog posts explains how to do that, but the concepts and architecture can be applied to any chatbot, including Slack bots, Slack slash commands, Facebook Messenger bots, etc. with some minor modifications.
While at first I wasn’t sure whether I would be able to develop software without a local IDE on the Pixelbook, I quickly found a way to have a comfortable development environment in the cloud — with Cloud Shell & Online Editor.
Target audience & technologies used
In the spirit of not wasting anyone’s time, if any of the following technologies are of interest to you, please read on:
- Hangouts Chat API
- Cloud Functions
- Cloud Pub/Sub
- Cloud Scheduler
- Cloud Firestore
- Cloud Shell & Online Editor
- Cloud Source Repositories (see blog post about monitoring)
- Stackdriver for logging and monitoring (see blog post about monitoring)
- Javascript
What are we going to develop?
A chatbot that helps users remember important events or tasks. It will look like this:
Architecture
Once a bot is added to a chat room or a 1:1 conversation with the bot is initiated, the following architecture outlines how to set a reminder and how the system notifies users of reminders due.
Set a reminder (Steps 1 to 6)
- User: Sends a message to @Reminder Bot in a chat room or a direct message to @Reminder Bot. E.g. “Go to sleep in five minutes”.
- Hangouts Chat: Creates a message for the mentioned bot.
- Hangouts Chat API: Publishes an event to a Cloud Pub/Sub topic. The event contains information about the user, the message content, timestamps, etc. More details in the docs.
- Cloud Pub/Sub: Invokes a Cloud Function to process each incoming event. The Cloud Function converts the user’s message, e.g. “Go to sleep in five minutes”, into a date (current time + 5 minutes) and subject (go to sleep).
- Cloud Function: Persists the reminder data in Cloud Firestore. This includes the reminder date, the subject and information on how to contact the user when the reminder is due.
- Cloud Function: Publishes a confirmation message (e.g. “Got it. I will remind you on xyz.”) to a Pub/Sub topic for further processing. If the user had sent an invalid message or had asked for help, the Cloud Function replies accordingly.
Send a message to a user (Steps A to D)
A. Cloud Pub/Sub: Invokes a Cloud Funtion to process outgoing messages. Any part of the system can publish an event to this Pub/Sub topic to send a message to the user.
B. Cloud Function: Uses the Hangouts Chat API Node.js package to process events from the Pub/Sub topic and send it to the Hangouts Chat API.
C. Hangouts Chat: Creates a message for the intended user.
D. User: Sees the message sent by the bot.
Notify users of their reminders (Steps 7 to 10)
7. Cloud Scheduler: Publishes a dummy event to a Pub/Sub topic every minute.
8. Cloud Pub/Sub: Invokes a Cloud Function to check the database for due reminders.
9. Cloud Firestore: Returns reminders due in the past and not yet flagged as successfully processed.
10. Cloud Function: If reminders are due, the function pushes an event to Pub/Sub and flags the reminders as processed — see “Send a message to a user” above. Otherwise, nothing happens.
Goals
As part of this project, I set the following goals:
- Develop, test, deploy & monitor in the cloud.
- Build a scalable foundation anyone can use to develop their own bot.
- Provide a corresponding Github repo with pull requests for each step along the way.
Development & Deployment Overview
Source code
The code is available on Github. Individual pull requests offer a better insight into smaller pieces of the overall project. On each git push, the code is mirrored to a Cloud Source Repository, which is used later to debug the services in production (if / when that feature becomes available for Cloud Functions).
Monorepo
All services are in a monorepo, managed by Lerna. I previously wrote about that in detail. When you see commands such as npx lerna ..., run them from the repo root.
Languages & tools
Each service is written in Javascript and NPM scripts take care of the rest. No tests 😰.
Terminal & editor
I use Cloud Shell as the terminal and the Online Editor to write the code. What’s nice about this setup is that Cloud Shell comes pre-loaded with all the development tools needed. Learn more about its features and limitations to see if it works for you.
Summary
While this is only the first part, I hope it gives a good overview of what this series of blog posts is about. The architecture applies to any kind of chatbot, whether it’s internal or public.
Together with the Github repo and all relevant pull requests, I hope this is a useful foundation for anyone to develop serverless chatbots on the Google Cloud Platform.
Please get in touch if you have any questions, feedback, feature requests, etc. I’d be happy to discuss any of that and learn more about your use case for chatbots.
Thank you Vincent
A special thank you goes to my friend Vincent who took the time to review the blog posts and source code. We architected and develoed chatbots together at a previous job and his insight and feedback was invaluable!
👏 ❤️
Next Steps
In order to complete the Reminder Bot, I suggest you continue with part 2 where you’ll learn how to process incoming messages.
Alternatively, head over to the monitoring post to learn more about Stackdriver error reporting, custom log metrics, etc.
