Chatbot framework in Clojure
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dev
doc/api
resources
src/jubot
test/jubot
.gitignore
LICENSE
README.md
project.clj

README.md

jubot

Circle CI Dependency Status

API Docs

jubot Chatbot framework in Clojure.

Currently, jubot supports following adapters and brains:

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.

Deploy

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.