Slappy

This gem support to make slack bot, inspire from hubot and sinatra.

Use the Slack Realtime API and Web API(see the official-documentation).

Quick Start

1. Generate Slack API Token

Slack API Token generate from official page.

2. Set environment variable to Slack API Token

Slappy references ENV['SLACK_TOKEN'] default.

3. Run generator

Execute then command to generate project:

$ slappy new project-name

If you want to use current directory, execute then command:

$ slappy new

(If you use bundler, add bundle exec prefix)

4. Write code

Create ruby file to under project-name/slappy-scripts, and written code.

Example:

# catch pattern
hear '^hello, slappy!' do |event|
  logger.info 'received message!'
  say 'hello!!', channel: event.channel #=> respond message to channel
end

There scripts not share scopes with other scripts.

5. Slappy start

Execute then command in project root directory.

$ slappy start

(Stop: Input Ctrl+c)

Installation

Add this line to your application's Gemfile:

gem 'slappy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install slappy

Usage

ENV

Store configuration value in environment variables. They are easy to change between deploys without changing any code.

SLACK_TOKEN - required (when not configured)

Configure

Configure default settings. There configrations effect on send message to slack when use say method and should override when option given.

Example

require 'slappy'

Slappy.configure do |config|
  config.token = 'foobar'
  config.robot.username   = 'slappy'
  config.robot.channel    = '#general'
  config.robot.icon_emoji = ':slappy:'
end

Slappy.say 'hello!' #=> username: slappy, channel: '#general', icon_emoji: ':slappy:'

Configuration Parameters

token            - default: ENV['SLACK_TOKEN']
scripts_dir_path - default : 'slappy-scripts'

robot.botname    - not effect now
robot.username   - default: 'slappy'
robot.icon_emoji - default: nil
robot.channel    - default: '#general'
robot.icon_url   - default: nil
robot.as_user    - default: false

Basic Usage

# called when start up
hello do
  logger.info 'successfly connected'
end

Send and Receive Message

# called when match message
hear 'foo' do
  logger.info 'foo'
end

# use regexp in string literal
hear 'bar (.*)' do |event|
  logger.info event.matches[1] #=> Event#matches return MatchData object
end

# event object is slack event JSON (convert to Hashie::Mash)
hear '^bar (.*)' do |event|
  say 'slappy!', channel: event.channel  #=> to received channel object
  say 'slappy!', channel: '#general'     #=> send to public channel
  say 'slappy!', channel: 'private-room' #=> send to private group
  say 'slappy!', username: 'slappy!', icon_emoji: ':slappy:' #=> change config
end

# use regexp literal
hear(/^foobar/) do
  logger.info 'slappppy!'
end

Monitoring Subtypes Event

monitor 'channel_joined' do |event|
  say "Welcome to #{event.name}!", channel: event.channel
end

monitor 'team_join' do |event|
  say "Welcome to this team!", channel: "#general"
end

Schedule Event

schedule '* * * * *' do
  logger.info 'Slappy alive...' #=> Repeat every minutes.
end

DSL Methods

method	when execute callback
hello	start up
hear	message (match pattern)
monitor	Slack RTM event
schedule	specify time (Syntax is here) - Thanks to Chrono!

In your Application

If you not want execute slappy start command, written by (require 'slappy/dsl' use DSL):

require 'slappy'

Slappy.hello do
  # In your code..
end

Slappy.say 'message to slack'

Slappy.start #=> Start WebSocket connection

Release Note

• v0.5.2

  • Add debug logging
  • Fix schedule id is not normality

• v0.5.1

  • Fix monitor event disabled

• v0.5.0

  • Support Schedule
  • Support Slack RMT Event
  • Support private group
  • Support as_user option
  • Introduce SlackAPI objects
  • Group
  • Channel
  • Direct
  • User

• v0.4.0

  • Support logger
  • Support load lib directory
  • Add New command
  • version
  • Choise dsl enabled in slappy_config

• v0.3.0

  • Introduce DSL
  • Introduce CLI commands
  • start
  • new
  • Use String literal for hear parameter
  • Chose dsl use in slappy_config

• v0.2.0

  • Modify interface

• v0.1.0

  • Release

Feature

• [ ] Execute in shell (because testable).
• [ ] Support private channel
• [ ] Support Schedule event (cron like)
• [ ] Add bot name
• [ ] client#respond (hubot#respond like)
• [ ] Split chat adapter

Contributing

1. Fork it ( http://github.com/wakaba260/slappy/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

The gem is available as open source under the terms of the MIT License.