Make Slack Bots in Java in Minutes

jbot framework — lego for building bots.

jbot is a spring-boot application 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.

you can start talking with your bot in just four easy steps:

1. clone this project $ git clone git@github.com:ramswaroop/jbot.git and $ cd jbot/jbot-example .
2. create a slack bot and get your slack token.
3. paste the token in application.properties file.
4. run the application by running jbotapplication in your ide or via command line $ mvn spring-boot:run .

that's it.

why use jbot 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 easier.
• receiving and 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.
• the conversation feature of jbot makes talking to your bot a breeze.
• well-tested with unit tests.

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 the 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 jbot

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 the application.properties file:

slackbottoken=xoxb-50014434-slacktokenx29u9x1bq
slashcommandtoken=x73fv3tokenx242cdpeq
slackincomingwebhookurl=https://hooks.slack.com/services/t02webhookurlv7ooyvpihl7y6

the core package contains all of jbot 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 events . 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, but the eventtype.ack event is nothing but an acknowledgement event that 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 " + slackservice.getcurrentuser().getname()));
    }
}

what you're doing here is annotating a method with the @controller annotation and passing an array of events to that annotation that 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-za-z ]{1,})(\\d+)([a-za-z ]{1,})")
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.

sending messages

in bots , you can use the reply() method defined in the 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!"
}

note: event , message , and richmessage are generic classes. not all the time, all the attributes present in them will have values. in other words, slack sends different responses for different events .

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 the 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 . a pattern attribute in the controller annotation has no effect for rest of the methods in a conversation.
• the first method in the conversation doesn't need to call nextconversation(event) , but the rest of the methods do need to.

deploy to the cloud

botkit is heroku-ready. to deploy, you need to perform the below simple steps:

1. clone this project $ git clone git@github.com:ramswaroop/jbot.git and $ cd jbot/jbot-example .
2. get your slack bot token or slash command token or incoming webhook url.
3. paste the above tokens/urls in the application.properties file.
4. download toolbelt for your system.
5. $ heroku login — log into 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.

this is just the tip of the iceberg. to explore/contribute/complain/donate, please visit jbot on github or view the latest documentation on my blog .