Hello, curious people!
We are all familiar with using bots for DMs and support services. If you are a developer using Oracle Digital Assistant (ODA), you might be aware that there are only a few out-of-the-box supported channels. Ever wondered about building an integration for any unsupported platform or if you can use bots in a group chat? If yes, you've come to the right place - read on to find out more.
Why would I want to add support for group chat? Great question! There are many good reasons for using bots in a group chat. Consider a group of people planning for a trip/organize a party or go to a movie and then the bot comes up with an itinerary/a place and a show time accordingly. That's not all, with the power of programming, you can enable the bot do anything from logging your daily work to performing complex automations all fully connected to back-end systems:
- Human Resources can use a bot through Hangouts to manage the on-boarding process, making the life of HR and your new employees easier ;)
- You can set-up a bot in Hangouts for employees to lodge suggestions, ideas or complaints.
- You can use a bot to raise a leave request in seconds.
- A bot can also be used to answer enquiries, incident management and can also interact with CRM systems to perform required tasks. And, what not? A bot literally can do anything with the power of programming.
Without further ado, I'll share all the details on how you to achieve this integration. This post assumes you are new to Google Cloud Platform (GCP) and Oracle Digital Assistant (ODA) .
The entire process can be broken down into 3 individual parts :
4. Final Steps
Before we look into the actual process, please make sure that your machine has Node.js. installed and running properly.
1. Setting up a bot in Hangouts Chat
To set up a bot in Hangouts Chat, you first need to login to your Google Cloud Platform (GCP) account.
If you're new to the GCP, you might see a pop up like this and you will have to accept the Terms, after choosing your country of residence:
- After agreeing to the terms you will see a dashboard: empty if you're a new user and list of projects if you are an existing user and has projects already.
If you don't have any projects already, you will have to create one by clicking on CREATE button.
If you're already a GCP user and want to add the Hangouts Chat API to the existing project, please choose a project by clicking on the drop down button available on the top left hand side.
- Give the project name and the location (if available) and click CREATE.
- After the project is created successfully, you will be presented with the project's dashboard. Next, add the Hangouts Chat API. You can do this by either clicking on "Enable APIs and Services" or "API Library" or "Library" from the navigation pane, as show in the below image.
- Search for Hangouts Chat API in the API Library and click on the result API.
- Click on the "Enable" button available in the Hangouts Chat API screen.
(You can even give this API a try in the Google API Explorer)
Enabling this API allows you to connect to Hangouts Chat from your project, which is exactly what we need.
After enabling the API, you will be presented with a dashboard to view/monitor the statistics and other properties of the corresponding API (Hangouts Chat API in this case) as shown below:
- To connect to this API from an external source, we will need to obtain credentials to the Project (HangoutsBotDemo). The credentials could be an API Key, an OAuth client ID or a Service Account key. If you are not sure what to use, you can answer a few questions and Google will let you know the type of credentials you will need. We will be using an API Key in this demo. To create credentials, click on the "CREATE CREDENTIALS" button available in the API dashboard.
You will be prompted to answer a few questions and then you will be shown a screen to name your security credentials.
Google recommends using OAuth for web servers but as this is a demo we will be using an API key. You can generate an API key by clicking on the credentials in your project dashboard and selecting API Key from the drop down as shown below.
The warning says to Restrict the key to prevent unauthorised usages. For more information on Restricting the API keys and best practices visit this link.
For this demo, copy the generated API Key and click "CLOSE". You might want to add additional security for the project if you are using this in "PRODUCTION MODE".
- After you have successfully created the key, we are only one step away from creating the bot.
To do this, go to your API Dashboard and go to Configuration from the Navigation Menu.
Provide a name, an Avatar URL and a description for the bot and choose the required functionality.
- We need a backend for this bot. This can be configured in the connection settings. You can choose one from the Bot URL, Apps Script Project and Cloud Pub/Sub. We will use the Bot URL for this project.The bot URL is a public URL of the Web Server application. You can host the web server app in any cloud service or you can run the server in your computer and expose the port using any tunneling software.The sample code runs on the port '5000'. Expose this port and obtain a public URL (I prefer using Ngrok. If you are new to ngrok, refer to the official documentation).
Hint: Execute the command 'ngrok http 5000' in the downloaded ngrok folder and make a note of the 'https' URL provided. The endpoints are predefined and you can change them in the code as you wish. If you do not wish to change any endpoint, append "/user/message" to the obtained ngrok URL and paste it in the Bot URL field.
You can set the permissions of your bot according to your requirements (i.e, you can make the bot visible to everyone in your organization or you can specify a set of people for the bot to be visible to).
You will also be provided with a verification token (which is being deprecated soon) to verify the authenticity of the incoming requests. For more information on verifying the bot authenticity, visit this link.
Click SAVE and that should create a bot with the given name.
You can view the bot from your Hangouts Chat app:
You can enable/disable the bot anytime from the STATUS drop-down.
With this, our first step is complete.
2. Setting up the web server application
First, let's understand why we need a web server application.
A Hangouts Chat Bot needs a backend that responds to the messages from the user. This backend could be anyone in the above mentioned types (An Apps Script Project, A Cloud Pub/Sub or a Web server).
To integrate ODA with any channel, we will need to set up a "webhook server" that makes use of the Webhook Client released by Oracle. In this particular integration we will set up a web server that acts as a backend for Hangouts Chat Bot and a webhook server for ODA as well.
The webhook server you are about to setup will transform ODA messages to Hangouts Chat accepted format and vice-versa acting as a middleware.
Please download a part of the code that packages the SDK as well as the web server from here (you can use this to build your own server or reach out to us for a fully working solution).
After cloning/downloading the above repository, you will need to provide configuration details in the "config.js" file, which you will obtain in the next step.
You may change the endpoints if you want to, in the index.js file but remember to use the changed endpoints during the configuration (in the Hangouts Chat and the ODA).
To start the server and finish up the integration we will need the webhook URL and a secret key from ODA which will be obtained in the next and the last step.
3. Create a webhook channel in ODA
- Login to ODA and navigate to "Channels".
- Click on "+Channel" to create a new channel.
- Provide the channel name, an optional description. Choose "Webhook " from the "Channel Type" dropdown as shown below. We will be using the "Platform Version 1.1 (default)".
- Provide the "Outgoing Webhook URI" (please don't forget to append the endpoint /user/message or your/own/endpoint) and click "Create".
- Enable the channel by clicking on the toggle next to "Channel Enabled" label, Route To the required Skill/Digital Assistant and take a note of the Secret Key and the Webhook URL as we will need to add this to the web server that we've already set up.
4. Final Steps
Now we have everything ready to finish up the integration. All we need to do is to configure the web server to send and receive messages from ODA.
To do this, go the config.js file and paste the copied Webhook URL at the url property, the secret key at the secret property and the API Key (from Google API) at the apiKey property.
Once you've done this, start the server using the command:
in the downloaded folder.
If you see no errors, congratulations! Your integration is successful.
The testing for this integration is pretty easy. You can simply search for the bot with name in the Hangouts Chat and start messaging.
Check out how messages are rendered in Hangouts Chat:
Now let's see how different message types are rendered in Hangouts Chat using the given code.
One thing to note, at the time of publishing the Hangouts Chat doesn't support "horizontal layout". To make it work, we make use of the vertical layout available to accomplish the integration.
Lists behave the same way as in other channels except that when an option is selected, the others will disappear and only the selected option remains on the screen. Like this:
Cards are shown in the vertical format with a title, subtitle, a very small image (with the size of an icon) and the postback button.
To make sure that the user can view the full size image, an onClick event is added to the image which opens the full image in the browser window.
This is how cards appear:
Note: Only PNG images are supported.
FAQs appear like this:
There is no out-of-the-box support for "lists". We modified the card template available for the Hangouts Chat to suit our needs.
The Group Chat Feature:
One advantage of having Bots in Hangouts Chat is that we can add them to groups, unlike many other channels. If your use case requires the inclusion of a chatbot in a group, Hangouts Chat can be a very handy channel.
Here are a few screenshots and representations of Hangouts Bot in a Chat Room (groups):
You can add an event and respond to it when the bot is added to a group. For more information on Events in Hangouts Chat please visit this page.
Initiating the conversation with the bot:
You can start chatting with the bot within a group by mentioning the name of the bot (using @botname) as shown below.
Receiving Bot Responses:
All the bot responses, in this SDK are grouped into one thread in the group chat. You can also create a separate thread per user which doesn't look good and also doesn't give a proper chat experience if the number of people in the group is more (it is purely your choice though). To accomplish this, change the value for the threadKey parameter at line 35, index.js file according to your requirement.
Multiple users can chat with the bot without losing the context. You can even have as many sessions as the users within the group chat. Again, that doesn't make any meaning for the group chat if everyone can talk to the bot individually, and it's my personal feeling.
The following snapshot shows one person responding to the bot's reply to another person.
Please feel free to improvise the code - comments/suggestions are welcome.
I would like to thank my colleague Sai Srikanth for putting his efforts in validating this post.