Houston::Slack

This module allows Houston to post messages on Slack and to listen (and respond) to conversations via Slack's Real Time Messaging API.

Communicating with Slack via its APIs is implemented by slacks.

Matching listeners to incoming messages is implemented by attentive.

Installation

In your Gemfile, add:

gem "houston-slack", github: "houston/houston-slack", branch: "master"

And in config/main.rb, add:

use :slack do
  token ENV["HOUSTON_SLACK_TOKEN"]
end

And then execute:

$ bundle

Usage

Configuration

To use Houston::Slack, you need to add add a new Bot User Integration to your Slack team. Slack will provide an API token for your user that starts with xoxb-. Copy the token into the use :slack block like this:

use :slack do
  token "xoxb-0000000000-abcdefghijklmnopqrstuvwx"
end

Sending messages

You can send messages from Houston with Houston::Slack.send.

send takes two arguments:

message — the message to be sent, a string
options — a hash of options including:
- :channel — (required) the channel to send the message to (e.g. @username or #general)
- :attachments, :username, :as_user, :parse, :link_names, :unfurl_links, :unfurl_media, :icon_url, :icon_emoji — (optional) are defined by Slack and passed through by Houston::Slack

Example

Houston::Slack.send "Hi! I'm Baymax, your personal healthcare companion.",
  channel: "#general"

Listening

Houston::Conversations.config do
  listen_for("hurry up") { |e| e.reply "I am not fast" }
  listen_for("fist bump") { |e| e.reply [":fist:", "ba da lata lata la"] }
end

Houston can also listen to any messages sent within the hearing of the Bot User. It does this by plugging those messages into Houston's Conversations system. To learn more about setting up—and responding to—listeners, see Houston::Conversations's README.

Slash Commands

Houston::Slack::Slash can respond to slash commands created for your team in Slack. A slash command sends Houston user inputed text and must receive a message in response.

When you create a slash command on Slack set the URL to http://houstondomain.com/slack/command and set the method to POST.

Example

This example responds to the slash command /weather where the user is expected to enter a zipcode.

Houston::Slack.config do
  slash("weather") do |e|
    zipcode = e.text
    weather = WeatherAPI.get_weather(zipcode)
    message = "Today is #{weather.to_s}"
    e.respond! message
  end
end

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request