BotKit

LEGO for building bots.

BotKit is a java application (inspired by Howdyai's Botkit) to make Slack (Facebook and Twitter coming soon) bots in minutes. It provides all the boilerplate code needed so that you can make your bot live right away.

SlackBot

Table of Contents

1. Getting started
2. Why use Botkit for Slack?
3. Basic Usage
4. Building a Slack Integration with Botkit
   • Setting up your app
   • Receiving messages
   • Sending messages
   • Conversations
   • Usage
   • Deploy to the cloud
5. Contributions
6. Donations

Getting started

Running your SlackBot is just 4 easy steps:

1. Clone this project $ git clone [email protected]:ramswaroop/botkit.git and $ cd botkit.
2. Create a slack bot and get your slack token.
3. Paste the token in application.properties file.
4. Run the application by running BotKitApplication in your IDE or via commandline $ mvn spring-boot:run.

You can now start talking with your bot ;)

Why use Botkit for Slack?

• Provides you with all the boilerplate code which handles underlying websocket connections and other complexities.
• Supports a few extra events in addition to all the events supported by Slack RTM API which makes your work a lot more easier.
• Receiving & sending messages is as easy as defining a controller method and calling reply(), you don't need to manually parse any events nor manually encode any messages before sending.
• Conversation feature of botkit makes talking to your bot a breeze.
• Well tested with unit tests.
• And many other features which can't just be mentioned here.

Basic Usage

The main function of a Bot is to receive and reply messages. With this kit, receiving messages is as easy as just writing a simple controller and replying to it by calling the reply() method as shown below:

@Controller(events = EventType.MESSAGE)
public void onReceiveDM(WebSocketSession session, Event event) {
    reply(session, event, new Message("Hi, I am a Slack Bot!"));
}

All the code for your bot goes in SlackBot class which extends Bot from the core package. You can have as many bots as you want, just make the class extend Bot class and it gets all the powers of a Slack Bot.

Building a Slack Integration with Botkit

You can integrate your services into Slack by any of the following ways:

• Bot users
• Slash Commands
• Slack Webhooks
• Slack Apps

And Botkit currently supports:

• Bot users via Slack Real Time Messaging (RTM) API
• Slack Slash Commands
• Slack Webhooks

Bots interact with Slack through RTM API or technically via Web Sockets. Slash Commands are nothing but GET and POST calls to your app. Finally, Webhooks can be of two types, Incoming and Outgoing. Incoming webhooks is where you POST data from outside (i.e, your app) to Slack and Outgoing webhooks is where Slack POST data to an endpoint you specify.

Setting up your app

You need to first paste your tokens/urls in application.properties file:

slackBotToken=xoxb-50014434-slacktokenx29U9X1bQ
slashCommandToken=X73Fv3tokenx242CdpEq
slackIncomingWebhookUrl=https://hooks.slack.com/services/T02WEBHOOKURLV7oOYvPiHL7y6

The core package contains all of Botkit code. You can create packages outside core package and put your custom code there. To make a

• Slack Bot ⇒ Extend Bot class.
• Slash Command Handler ⇒ Annotate your class with Spring's @Controller and have a method with the required @RequestMapping path receiving a set of request params as shown in the sample.
• Slack Incoming Webhook ⇒ Just make a POST call with RichMessage whenever you want to update your Slack users about something.
• Slack Outgoing Webhook ⇒ Same as Slash Command Handler.

Receiving Messages

For Bots, you receive a message as Event. For almost all actions Slack fires a relevant event for it. Unfortunately, it does not fire appropriate events when someone directly messages the bot (direct message) or mentions the bot on a channel (like @bot). It just fires an event of type message for all the messages (directly to bot and to channels where bot is a member) sent.

But guess what, you're at the right place now, BotKit handles that for you. It supports three extra events EventType.DIRECT_MESSAGE, EventType.DIRECT_MENTION and EventType.ACK in addition to all the currently supported Slack events. The first two events are self-explanatory, the EventType.ACK event is nothing but an acknowledgement event which acknowledges the delivery of a previously sent message.

To receive and parse slack bot events you just need to have this:

@Controller(events = {EventType.DIRECT_MENTION, EventType.DIRECT_MESSAGE})
public void onReceiveDM(WebSocketSession session, Event event) {
    if (event.getText().contains("hi")) {
        reply(session, event, new Message("Hi, I am " + currentUser.getName()));
    }
}

What you're doing here is annotating a method with @Controller annotation and passing an array events to that annotation which you want to listen to. By default your controller will listen to EventType.MESSAGE events if you do not specify any events explicitly.

You can also add regular expressions to your @Controller annotation like:

@Controller(events = EventType.MESSAGE, pattern = "^([a-z ]{2})(\\d+)([a-z ]{2})$")
public void onReceiveMessage(WebSocketSession session, Event event, Matcher matcher) {
    reply(session, event, new Message("First group: " + matcher.group(0) + "\n" +
            "Second group: " + matcher.group(1) + "\n" +
            "Third group: " + matcher.group(2) + "\n" +
            "Fourth group: " + matcher.group(3)));
}

You can optionally have the matcher as a formal parameter in the method if you want to work on the values sent by the user. But do keep the order of parameters as shown above.

In Slash Commands, you receive a GET or POST request as below:

token=gIkuvaNzQIHg97ATvDxqgjtO
team_id=T0001
team_domain=example
channel_id=C2147483705
channel_name=test
user_id=U2147483697
user_name=Steve
command=/weather
text=94070
response_url=https://hooks.slack.com/commands/1234/5678

If you have configured for POST requests, data will be sent to your URL with a content-type header set as application/x-www-form-urlencoded. If you've chosen to have your slash command's URL receive invocations as a GET request, no explicit content-type header will be set.

NOTE: The URL you provide must be a HTTPS URL with a valid, verifiable SSL certificate.

In Incoming Webhooks, your application POST data and do not receive any data apart from the acknowledgement for your sent data. You send data as RichMessage to Slack Webhook URL.

In Outgoing Webhooks, you receive a POST request from Slack like below:

token=mbxmjpceetMUz2hfecqM31KC
team_id=T0001
team_domain=example
channel_id=C2147483705
channel_name=test
timestamp=1355517523.000005
user_id=U2147483697
user_name=Steve
text=googlebot: What is the air-speed velocity of an unladen swallow?
trigger_word=googlebot:

Please note that the content of message attachments will not be included in the outgoing POST data in case of Outgoing Webhooks.

Sending Messages

In Bots, you can use the reply() method defined in Bot class to send messages to Slack. You just need to set the text you want to send in Message and everything else will be taken care by BotKit. But you can set other fields if you want such as id in the message.

Here is an example:

@Controller(events = EventType.MESSAGE)
public void onReceiveMessage(WebSocketSession session, Event event) {
    reply(session, event, new Message("Hi, this is a message!"));
}

Under the hood the message sent is nothing but a json like below:

{
    "id": 1,
    "type": "message",
    "channel": "C024BE91L",
    "text": "Hi, this is a message!"
}

For Slash Commands and Incoming Webhooks, you can send messages as RichMessage. Just keep in mind to encode it before sending by just calling the encodedMessage() method. Below is an example:

@RequestMapping(value = "/slash-command",
            method = RequestMethod.POST,
            consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public RichMessage onReceiveSlashCommand(@RequestParam("token") String token,
                                         @RequestParam("team_id") String teamId,
                                         @RequestParam("team_domain") String teamDomain,
                                         @RequestParam("channel_id") String channelId,
                                         @RequestParam("channel_name") String channelName,
                                         @RequestParam("user_id") String userId,
                                         @RequestParam("user_name") String userName,
                                         @RequestParam("command") String command,
                                         @RequestParam("text") String text,
                                         @RequestParam("response_url") String responseUrl) {
    // validate token
    if (!token.equals(slackToken)) {
        return new RichMessage("Sorry! You're not lucky enough to use our slack command.");
    }        
    
    /** build response */
    RichMessage richMessage = new RichMessage("The is Slash Commander!");
    richMessage.setResponseType("in_channel");
    // set attachments
    Attachment[] attachments = new Attachment[1];
    attachments[0] = new Attachment();
    attachments[0].setText("I will perform all tasks for you.");
    richMessage.setAttachments(attachments);
    return richMessage.encodedMessage(); // don't forget to send the encoded message to Slack
}

Points to Note:

• Event, Message and RichMessage are generic models. Not all the time, all the attributes present in them will have values. In other words, Slack sends different responses for different events.
• You need a channel id to send replies. Therefore, you can use reply() method for events which have a channel id in them or else you have to explicitly set the channel id in the Message object.

Conversations

This is the most wonderful feature of botkit, with this you can literally talk to your bot and have a conversation. See below for an example as to how your bot sets up a meeting for your team by asking some simple questions one after the other.

    /**
     * Conversation feature of Botkit. This method is the starting point of the conversation (as it
     * calls {@link Bot#startConversation(Event, String)} within it. You can chain methods which will be invoked
     * one after the other leading to a conversation. You can chain methods with {@link Controller#next()} by
     * specifying the method name to chain with.
     *
     * @param session
     * @param event
     */
    @Controller(pattern = "(setup meeting)", next = "confirmTiming")
    public void setupMeeting(WebSocketSession session, Event event) {
        startConversation(event, "confirmTiming");   // start conversation
        reply(session, event, new Message("Cool! At what time (ex. 15:30) do you want me to set up the meeting?"));
    }

You can start a conversation by calling startConversation(event, nextMethodName) within your controller. You can pass the event and the name of the next controller method.

    /**
     * This method is chained with {@link SlackBot#setupMeeting(WebSocketSession, Event)}.
     *
     * @param session
     * @param event
     */
    @Controller(next = "askTimeForMeeting")
    public void confirmTiming(WebSocketSession session, Event event) {
        reply(session, event, new Message("Your meeting is set at " + event.getText() +
                ". Would you like to repeat it tomorrow?"));
        nextConversation(event);    // jump to next question in conversation
    }

This is your next method in the conversation. After your desired work is done, do not forget to call nextConversation(event) to jump to the next method. You can specify the next method to call in next attribute of Controller annotation.

    /**
     * This method is chained with {@link SlackBot#confirmTiming(WebSocketSession, Event)}.
     *
     * @param session
     * @param event
     */
    @Controller(next = "askWhetherToRepeat")
    public void askTimeForMeeting(WebSocketSession session, Event event) {
        if (event.getText().contains("yes")) {
            reply(session, event, new Message("Okay. Would you like me to set a reminder for you?"));
            nextConversation(event);    // jump to next question in conversation  
        } else {
            reply(session, event, new Message("No problem. You can always schedule one with 'setup meeting' command."));
            stopConversation(event);    // stop conversation only if user says no
        }
    }

    /**
     * This method is chained with {@link SlackBot#askTimeForMeeting(WebSocketSession, Event)}.
     *
     * @param session
     * @param event
     */
    @Controller
    public void askWhetherToRepeat(WebSocketSession session, Event event) {
        if (event.getText().contains("yes")) {
            reply(session, event, new Message("Great! I will remind you tomorrow before the meeting."));
        } else {
            reply(session, event, new Message("Oh! my boss is smart enough to remind himself :)"));
        }
        stopConversation(event);    // stop conversation
    }

To end the conversation, call stopConversation(event) inside your controller method.

NOTE:

• Only the first method in a conversation can define a pattern. pattern attribute in Controller annotation has no effect for rest of the methods in a conversation.
• The first method in the conversation need not call nextConversation(event) but rest of the methods do need to.

Usage

You can directly clone this project and start coding your bot (just don't touch the core package) or you can include it as a maven/gradle dependency.

Maven

<dependency>
    <groupId>me.ramswaroop.botkit</groupId>
    <artifactId>botkit</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

dependencies {
    compile("me.ramswaroop.botkit:botkit:1.0.0")
}

Deploy to the Cloud

Bokit is Heroku ready. To deploy, you need to perform the below simple steps:

1. Clone this project $ git clone [email protected]:ramswaroop/botkit.git and $ cd botkit.
2. Get your slack bot token or slash command token or incoming webhook url.
3. Paste the above tokens/urls in application.properties file.
4. Download Toolbelt for your system.
5. $ heroku login - Login to Heroku.
6. $ heroku create - Create an app on Heroku.
7. $ git push heroku master - Push your code to Heroku.
8. $ heroku ps:scale web=1 - Start your application.

You can now start talking with your Bot, send commands to your Slash Command or play with Incoming Webhooks ;)

Contributions

If you would like like to contribute, raise an issue on Github and I would be more than happy to discuss :)

Donations

Buy me a coffee so that I stay awake whole night and complete Botkit soon enough :D