jubot

API Docs

Chatbot framework in Clojure.

Currently, jubot supports following adapters and brains:

• Adapter
• Slack
• Brain
• Redis

Why jubot?

• Simplicity
• Handlers are simple functions, and these are TESTABLE.
• Efficiency
• Supports REPL friendly development that you love.
• Extensibility
• Easy to exntend system because jubot uses stuartsierra/component as a component system.

Getting Started

$ lein new jubot YOUR_JUBOT_PROJECT
$ cd YOUR_JUBOT_PROJECT
$ lein repl
user=> (in "jubot help")

Handlers

Handler is a function to process user input.

Ping pong example:

NOTE: This example will response for any addresses because example code does not check :message-for-me?.

(defn ping-handler
  "jubot ping - reply with 'pong'"
  [{:keys [text]}]
  (if (= "ping" text) "pong"))

• Arguments
• :user: User name
• :text: Input string.
• :to: Address username.
• :message-for-me?: Is inputted message addredded to bot or not.
• Document string
• Document string will be shown in chatbot help.

user=> (in "jubot help")

Or you can use handler/regexp:

(ns foo.bar
  (:require
    [jubot.handler :as jh]))

(defn ping-handler
  [arg]
  (jh/regexp arg
    #"^ping$" (constantly "pong")))

Which handlers are collected automatically?

Developers do not need to specify which handlers are used, because jubot collects handler functions automatically.

• Public functions that matches /^.*-handler$/ in ns-prefix will be collected automatically.
• ns-prefix is a namespace regular expression. It is defined in YOUR_JUBOT_PROJECT.core.
• However, namespaces that matches /^.*-test$/ is excluded.

Schedules

Schedule is a function that is called periodically as a cron.

Good morning/night example:

(ns foo.bar
  (:require
    [jubot.scheduler :as js]))

(def good-morning-schedule
  (js/schedules
    "0 0 7 * * * *"  (fn [] "good morning")
    "0 0 21 * * * *" (fn [] "good night")))

• Use scheduler/schedule or scheduler/schedules to define one or more schedules.
• If the function returns string, jubot sends the string to adapter as a message. In other words, jubot does nothing when the function returns other than string.
• Scheduling format
• Jubot uses cronj for scheduling tasks, and scheduling format's details is here: cronj format

Which schedules are collected automatically?

As same as handler section, jubot collects schedule functions automatically.

• Public schedule funtion that matches /^.*-schedule$/ in ns-prefix will be collected automatically.
• Test namespaces that matches /^.*-test$/ are excluded.

Development in REPL

Jubot provides some useful funcition to develop chatbot in REPL efficiently. These functions are defined in dev/user.clj.

user=> (start)   ; start jubot system
user=> (stop)    ; stop jubot system
user=> (restart) ; reload sources and restart jubot system
user=> (in "jubot ping")

Command line arguments

Adapter name: -a, --adapter

• Default value is "slack"
• Possible adapter names are as follows:
• slack
• repl (for development)

Brain name: -b, --brain

• Default value is "memory"
• Possible brain names are as follow:
• redis
• memory (for development)

Chatbot name: -n, --name

• Default value is "jubot"

Deploy to Heroku

1. Edit Procfile as you want
2. Create and deploy (the following sample uses Redis as a brain)

heroku apps:create
heroku addons:add rediscloud
git push heroku master

Or use following deployment button based on jubot-sample.

Slack setting

• Required integration
• Outgoing WebHooks
• Incoming WebHooks
• Required environmental variables

heroku config:add SLACK_OUTGOING_TOKEN="aaa"
heroku config:add SLACK_INCOMING_URL="bbb"

Advanced setting for heroku

• Avoid sleeping app

heroku config:add AWAKE_URL="Application url on heroku"

License

Copyright (C) 2015 uochan

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.