If you’re an application developer, you’ve already heard about the growing wave of chat bots. One of the great advantages of a chat bot over a web or mobile application is that, if done correctly, it doesn’t require a user to leave the place they are already working. A chat bot can be made available via text message, through a sidebar on a webpage, or even as a member in a group chat, providing value where it is most needed.
This tutorial, the first in a series, demonstrates how the IBM Watson Conversation service can be integrated with the Slack platform to connect with a third-party source of information—in this case, the Google Calendar API. The end goal is to enable you to create a Slack bot that can actively listen to conversations in a channel and assist with scheduling meetings.
At this first stage, your Slack bot will be able to:
- Get permissions for multiple users’ calendars
- Query the calendars for busy times
- Query the calendars for free times
We’ve built this tutorial in Python and provided all the code here. Clone that repo and let’s get started!
The birth of your Slack bot
A lot of smart people have already written about how to build a Slack bot, so I’m not going to rehash here. Instead, I’d like to point you to this excellent tutorial by Matt Makai (Developer Evangelist at Twilio and speaker at the Watson Developer Conference). Matt gives you all the steps necessary to get your bot set up, and we’ve used what he shared as the starting point for our bot.
If you haven’t already, start by cloning our sample repo. Once you’ve done this, rename the folder to ‘slack-starterbot’, and navigate to this folder from your command line At this point, follow the steps in Matt’s tutorial, up until the ‘Coding Our StarterBot’ section. You can name your bot whatever you’d like (we’ve named ours ‘watson’, surprised?), just make sure you store your BOT_ID and SLACK_BOT_TOKEN as environment variables. In your repo you’ll find a ‘starterbot.py’ file ready to go with all the extra code for authenticating to Google and connecting to the Watson Conversation service.
Google Calendar authentication
Google uses OAuth2 for their Calendar API, which asks the user to provide explicit permission for your application. We’ll discuss how we handle this in Slack, but you will first need to obtain some application credentials from Google. To do this, go here and follow steps 1 and 2. When you download your ‘client_secret.json’ file, make sure to save it in your ‘slack-starterbot’ directory.
The authentication flow consists of three steps:
- User sends a message to your bot, and the bot returns a URL. This URL is generated by the ‘get_auth_url’ method in the ‘starterbot.py’ file and uses the information in the ‘client_secret.json’ file. This is what the process looks like for the user:
- User clicks on link, launching an authentication page. Once the user accepts, this redirects to a page with a token.
- The user copies the token and shares with the Slack bot. This is handled in the ‘set_auth_token’ method.
Once a user has authenticated, they will no longer need to go through this process.
Training Conversation intents
It would be easy to build your Slack bot to follow a few simple commands, such as “show my schedule.” But remember, the goal is to have a bot that can listen in to conversations and provide help at the appropriate times. This requires some natural language understanding, which is where the Watson Conversation service will help.
In this first stage, you are going to train the Watson Conversation service to recognize two similar but distinct categories of request: show me my schedule, and tell me what free times I have available. No matter what words the user chooses, you want to provide the information formatted in a way that directly matches the request. For example, if I ask about free times I don’t want details about the meetings that are on my calendar, but if I am asking about my schedule this is important information.
I’ve already written about how to get started with Watson Conversation, so I’ll dive right in to the intents you are training for. If you’d like to use what we’ve already built out, upload the ‘calendar_bot.json’ file from the cloned repo as a new Conversation workspace. For this bot, we’re focusing on two main intents. We’ve named them “#schedule” and “#free_time,” and the training data for both looks like this:
You’ll notice there are other intents as well, including “#greetings,” “#goodbyes,” and “#anything_else.” These help drive a very simple dialog for any user input that doesn’t match one of our main tasks:
Now that you’ve configured and trained your Conversation instance, you’ll want to include it in your ‘starterbot.py’ script. The first step is to get the Workspace ID as well as the user name and password for your Conversation instance. You’ll find a spot for this information near the top of ‘starterbot.py’. Next, you’ll want to install the Watson Developer Cloud Python SDK:
pip install watson-developer-cloud
In the ‘handle_command’ method, you can see a call to the Conversation endpoint. Once the user has been authenticated, you pass all input to the Conversation service. If the intent is either “#schedule” or “#free_time,” a call is made to the ‘calendar_usage’ method to get up to ten upcoming events using the Google Calendar API. Depending on the specific intent, the response will be formatted differently. Schedule requests look like this:
And requests for free time look like this:
Finally, any other input will be handled according to our simple dialog:
With the Slack bot set up, authentication ready to go, and a Watson Conversation instance trained and connected, you have everything you need to get your Slack bot working. As mentioned above, this is only the first stage. There are a number of improvements that can be made, including:
- Using entity detection to pick out specific days and times for more refined calendar searches
- Comparing calendars for multiple users to find common free times
- Making the bot an active listener that provides useful information when appropriate, without needing to be explicitly addressed
In future tutorials we will dig into this list of additional functionality and further explore the features of the Watson Conversation service and the Slack platform. If you have questions or feedback, please let us know!