Home

Botkit - Building Blocks for Building Bots

Botkit is designed to ease the process of designing and running useful, creative bots that live inside popular messaging platforms, including:

Getting Started

There are two basic ways to start a Botkit project:

Install Botkit directly from NPM or Github and build a new app from scratch, or use one of the included examples as a starting point.
Install the a Botkit Starter Kit ) and build on top of an already fully functioning bot that comes pre-configured with popular middleware plug-ins and components.

Install Botkit from NPM or Github

Botkit is available via NPM.

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

Once installed, 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.

Currently Botkit can connect to the following platforms

Install Botkit using a starter kit

Todo: list all known starter kits

Botkit Studio

Botkit Studio is a hosted development environment for bots from the same team that built Botkit. Based on feedback from the developer community, as well as experience running our flagship Botkit-powered bot, Howdy, the tools in Botkit Studio allow bot designers and developers to manage many aspects of bot behavior without writing additional code.

Start building your bot with Botkit Studio and you'll start from day one with extra tools and features that help you create and manage a successful bot application. It is also possible to add Studio features to your existing Botkit application. With a few lines of code, you can add access new features and APIs.

Botkit Studio is built on top of Botkit, so everything that works with Botkit continues to just work. All of the available plugins and middleware are compatible!

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, 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:

Read more about connecting your bot to Slack, connecting your bot to Facebook, connecting your bot to Twilio, or connecting your bot to Microsoft Bot Framework

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.');

});

Botkit Statistics Gathering

As of version 0.4, Botkit records anonymous usage statistics about Botkit bots in the wild. These statistics are used by the Botkit team at Howdy to measure and analyze the Botkit community, and help to direct resources to the appropriate parts of the project.

We take the privacy of Botkit developers and their users very seriously. Botkit does not collect, or transmit any message content, user data, or personally identifiable information to our statistics system. The information that is collected is anonymized inside Botkit and converted using one-way encryption into a hash before being transmitted.

Opt Out of Stats

To opt out of the stats collection, pass in the stats_optout parameter when initializing Botkit, as seen in the example below:

var controller = Botkit.slackbot({
    stats_optout: true
});