README
Botkit - Building Blocks for Building Bots
Botkit is designed to ease the process of designing and running useful, creative bots that live inside Slack, Facebook Messenger, Twilio IP Messaging, and other messaging platforms.
It provides a semantic interface to sending and receiving messages so that developers can focus on creating novel applications and experiences instead of dealing with API endpoints.
Botkit features a comprehensive set of tools to deal with popular messaging platforms, including:
Installation
Botkit is available via NPM.
bash
npm install --save botkit
You can also check out Botkit directly from Git. If you want to use the example code and included bots, it may be preferable to use Github over NPM.
git clone git@github.com:howdyai/botkit.git
After cloning the Git repository, you have to install the node dependencies. Navigate to the root of your cloned repository and use npm to install all necessary dependencies.
npm install
Use the --production flag to skip the installation of devDependencies from Botkit. Useful if you just wish to run the example bot.
npm install --production
Getting Started
After you've installed Botkit, the first thing you'll need to do is register your bot with a messaging platform, and get a few configuration options set. This will allow your bot to connect, send and receive messages.
The fastest way to get a bot online and get to work is to start from one of the examples included in the repo.
If you intend to create a bot that lives in Slack, follow these instructions for attaining a Bot Token.
If you intend to create a bot that lives in Facebook Messenger, follow these instructions for configuring your Facebook page.
If you intent to create a bot that lives inside a Twilio IP Messaging client, follow these instructions for configuring your app.
Core Concepts
Bots built with Botkit have a few key capabilities, which can be used to create clever, conversational applications. These capabilities map to the way real human people talk to each other.
Bots can hear things. Bots can say things and reply to what they hear.
With these two building blocks, almost any type of conversation can be created.
To organize the things a bot says and does into useful units, Botkit bots have a subsystem available for managing multi-message conversations. Conversations add features like the ability to ask a question, queue several messages at once, and track when an interaction has ended. Handy!
After a bot has been told what to listen for and how to respond, it is ready to be connected to a stream of incoming messages. Currently, Botkit supports receiving messages from a variety of sources:
- Slack Real Time Messaging (RTM)
- Slack Incoming Webhooks
- Slack Slash Commands
- Facebook Messenger Webhooks
- Twilio IP Messaging
Read more about connecting your bot to Slack, connecting your bot to Facebook, or connecting your bot to Twilio.
Included Examples
These examples are included in the Botkit Github repo.
slack_bot.js An example bot that can be connected to your team. Useful as a basis for creating your first bot!
facebook_bot.js An example bot that can be connected to your Facebook page. Useful as a basis for creating your first bot!
twilio_ipm_bot.js An example bot that can be connected to your Twilio IP Messaging client. Useful as a basis for creating your first bot!
examples/demo_bot.js another example bot that uses different ways to send and receive messages.
examples/team_outgoingwebhook.js an example of a Botkit app that receives and responds to outgoing webhooks from a single team.
examples/team_slashcommand.js an example of a Botkit app that receives slash commands from a single team.
examples/slackbutton_bot.js an example of using the Slack Button to offer a bot integration.
examples/slackbutton_incomingwebhooks.js an example of using the Slack Button to offer an incoming webhook integration. This example also includes a simple form which allows you to broadcast a message to any team who adds the integration.
example/sentiment_analysis.js a simple example of a chatbot using sentiment analysis. Keeps a running score of each user based on positive and negative keywords. Messages and thresholds can be configured.
Basic Usage
Here's an example of using Botkit with Slack's real time API, which is the coolest one because your bot will look and act like a real user inside Slack.
This sample bot listens for the word "hello" to be said to it -- either as a direct mention ("@bot hello") or an indirect mention ("hello @bot") or a direct message (a private message inside Slack between the user and the bot).
The Botkit constructor returns a controller object. By attaching event handlers
to the controller object, developers can specify what their bot should look for and respond to,
including keywords, patterns and various messaging and status events.
These event handlers can be thought of metaphorically as skills or features the robot brain has -- each event handler defines a new "When a human says THIS the bot does THAT."
The controller object is then used to spawn() bot instances that represent
a specific bot identity and connection to Slack. Once spawned and connected to
the API, the bot user will appear online in Slack, and can then be used to
send messages and conduct conversations with users. They are called into action by the controller when firing event handlers.
var Botkit = require('botkit');
var controller = Botkit.slackbot({
debug: false
//include "log: false" to disable logging
//or a "logLevel" integer from 0 to 7 to adjust logging verbosity
});
// connect the bot to a stream of messages
controller.spawn({
token: <my_slack_bot_token>,
}).startRTM()
// give the bot something to listen for.
controller.hears('hello',['direct_message','direct_mention','mention'],function(bot,message) {
bot.reply(message,'Hello yourself.');
});
Developing with Botkit
Table of Contents
Responding to events
Once connected to a messaging platform, bots receive a constant stream of events - everything from the normal messages you would expect to typing notifications and presence change events. The set of events your bot will receive will depend on what messaging platform it is connected to.
All platforms will receive the message_received event. This event is the first event fired for every message of any type received - before any platform specific events are fired.
controller.on('message_received', function(bot, message) {
// carefully examine and
// handle the message here!
// Note: Platforms such as Slack send many kinds of messages, not all of which contain a text field!
});
Due to the multi-channel, multi-user nature of Slack, Botkit does additional filtering on the messages (after firing message_recieved), and will fire more specific events based on the type of message - for example, direct_message events indicate a message has been sent directly to the bot, while direct_mention indicates that the bot has been mentioned in a multi-user channel.
List of Slack-specific Events
Twilio IPM bots can also exist in a multi-channel, multi-user environmnet. As a result, there are many additional events that will fire. In addition, Botkit will filter some messages, so that the bot will not receive it's own messages or messages outside of the channels in which it is present. List of Twilio IPM-specific Events
Facebook messages are fairly straightforward. However, because Facebook supports inline buttons, there is an additional event fired when a user clicks a button. List of Facebook-specific Events
Receiving Messages
Botkit bots receive messages through a system of specialized event handlers. Handlers can be set up to respond to specific types of messages, or to messages that match a given keyword or pattern.
These message events can be handled by attaching an event handler to the main controller object. These event handlers take two parameters: the name of the event, and a callback function which is invoked whenever the event occurs. The callback function receives a bot object, which can be used to respond to the message, and a message object.
// reply to any incoming message
controller.on('message_received', function(bot, message) {
bot.reply(message, 'I heard... something!');
});
// reply to a direct mention - @bot hello
controller.on('direct_mention',function(bot,message) {
// reply to _message_ by using the _bot_ object
bot.reply(message,'I heard you mention me!');
});
// reply to a direct message
controller.on('direct_message',function(bot,message) {
// reply to _message_ by using the _bot_ object
bot.reply(message,'You are talking directly to me');
});
Matching Patterns and Keywords with hears()
In addition to these traditional event handlers, Botkit also provides the hears() function,
which configures event handlers based on matching specific keywords or phrases in the message text.
The hears function works just like the other event handlers, but takes a third parameter which
specifies the keywords to match.
| Argument | Description |
|---|---|
| patterns | An array or a comma separated string containing a list of regular expressions to match |
| types | An array or a comma separated string of the message events in which to look for the patterns |
| middleware function | optional function to redefine how patterns are matched. see Botkit Middleware |
| callback | callback function that receives a message object |
controller.hears(['keyword','^pattern