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.
Running your SlackBot is just 4 easy steps:
- Clone this project
$ git clone [email protected]:ramswaroop/botkit.git
and$ cd botkit
. - Create a slack bot and get your slack token.
- Paste the token in application.properties file.
- Run the application by running
BotKitApplication
in your IDE or via commandline$ mvn spring-boot:run
.
You can now start talking with your bot ;)
- 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 callingreply()
, 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.
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:
And Botkit currently supports:
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.
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.
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-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.
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.
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
}
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.
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 inController
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.
<dependency>
<groupId>me.ramswaroop.botkit</groupId>
<artifactId>botkit</artifactId>
<version>1.0.0</version>
</dependency>
dependencies {
compile("me.ramswaroop.botkit:botkit:1.0.0")
}
Bokit is Heroku ready. To deploy, you need to perform the below simple steps:
- Clone this project
$ git clone [email protected]:ramswaroop/botkit.git
and$ cd botkit
. - Get your slack bot token or slash command token or incoming webhook url.
- Paste the above tokens/urls in application.properties file.
- Download Toolbelt for your system.
$ heroku login
- Login to Heroku.$ heroku create
- Create an app on Heroku.$ git push heroku master
- Push your code to Heroku.$ 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 ;)
If you would like like to contribute, raise an issue on Github and I would be more than happy to discuss :)
Buy me a coffee so that I stay awake whole night and complete Botkit soon enough :D