A simple wrapper to send notifications to Slack webhooks.
require 'slack-notifier'
notifier = Slack::Notifier.new "WEBHOOK_URL"
notifier.ping "Hello World"
# => if your webhook is setup, will message "Hello World"
# => to the default channel you set in slackInstall the latest stable release:
$ gem install slack-notifier
Or with Bundler, add it to your Gemfile:
gem "slack-notifier"On initialization you can set default payloads by calling defaults in an initialization block:
notifier = Slack::Notifier.new "WEBHOOK_URL" do
defaults channel: "#default",
username: "notifier"
end
notifier.ping "Hello default"
# => will message "Hello default"
# => to the "#default" channel as 'notifier'To get the WEBHOOK_URL you need:
- go to https://slack.com/apps/A0F7XDUAZ-incoming-webhooks
- choose your team, press configure
- in configurations press add configuration
- choose channel, press "Add Incoming WebHooks integration"
You can also set defaults through an options hash:
notifier = Slack::Notifier.new "WEBHOOK_URL", channel: "#default",
username: "notifier"These defaults are over-ridable for any individual ping.
notifier.ping "Hello random", channel: "#random"
# => will ping the "#random" channelSlack requires links to be formatted a certain way, so the default middlware stack of slack-notifier will look through your message and attempt to convert any html or markdown links to slack's format before posting.
Here's what it's doing under the covers:
message = "Hello world, [check](http://example.com) it <a href='http://example.com'>out</a>"
Slack::Notifier::Util::LinkFormatter.format(message)
# => "Hello world, <http://example.com|check> it <http://example.com|out>"Slack supports various different formatting options. For example, if you want to alert an entire channel you include <!channel> in your message
message = "<!channel> hey check this out"
notifier.ping message
#ends up posting "@channel hey check this out" in your Slack channelYou can see Slack's message documentation here
Since sequences starting with < have special meaning in Slack, you should use Slack::Notifier::Util::Escape.html if your messages may contain &, < or >.
link_text = Slack::Notifier::Util::Escape.html("User <[email protected]>")
message = "Write to [#{link_text}](mailto:[email protected])"
notifier.ping messageThis plugin supports the Slack blocks format and block kit builder. This is useful for displaying buttons, dropdowns, and images.
blocks = [
{
"type": "image",
"title": {
"type": "plain_text",
"text": "image1",
"emoji": true
},
"image_url": "https://api.slack.com/img/blocks/bkb_template_images/onboardingComplex.jpg",
"alt_text": "image1"
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "Hey there 👋 I'm TaskBot. I'm here to help you create and manage tasks in Slack.\nThere are two ways to quickly create tasks:"
}
}
]
notifier.post(blocks: blocks)Any key passed to the post method is posted to the webhook endpoint. Check out the Slack webhook documentation for the available parameters.
Setting an icon:
notifier.post text: "feeling spooky", icon_emoji: ":ghost:"
# or
notifier.post text: "feeling chimpy", icon_url: "http://static.mailchimp.com/web/favicon.png"Adding attachments:
a_ok_note = {
fallback: "Everything looks peachy",
text: "Everything looks peachy",
color: "good"
}
notifier.post text: "with an attachment", attachments: [a_ok_note]With the default HTTP client, you can send along options to customize its behavior as :http_options params when you post or initialize the notifier.
notifier = Slack::Notifier.new 'WEBHOOK_URL', http_options: { open_timeout: 5 }
notifier.post text: "hello", http_options: { open_timeout: 10 }Note: you should only send along options that Net::HTTP has as setters, otherwise the option will be ignored and show a warning.
:http_options can be used if you need to connect to Slack via an HTTP proxy.
For example, to connect through a local squid proxy the following options would be used.
notifier = Slack::Notifier.new 'WEBHOOK_URL', http_options: {
proxy_address: 'localhost',
proxy_port: 3128,
proxy_from_env: false
}There is a packaged default client wrapping Net::HTTP, but your HTTP needs might be a little different. In that case, you can pass in your own wrapper to handle sending the notifications. It just needs to respond to ::post with the arguments of the endpoint URI, and the payload pretty much the same as Net:HTTP.post_form.
A simple example:
module Client
def self.post uri, params={}
Net::HTTP.post_form uri, params
end
end
notifier = Slack::Notifier.new 'WEBHOOK_URL' do
http_client Client
endIt's also encouraged for any custom HTTP implementations to accept the :http_options key in params.
Setting client per post
You can also set the http_client per-post if you need to special case certain pings.
notifier.post text: "hello", http_client: CustomClientSetting a No-Op client
In development (or testing), you may want to watch the behavior of the notifier without posting to slack. This can be handled with a no-op client.
class NoOpHTTPClient
def self.post uri, params={}
# bonus, you could log or observe posted params here
end
end
notifier = Slack::Notifier.new 'WEBHOOK_URL' do
http_client NoOpHTTPClient
endBy default slack-notifier ships with middleware to format links in the message & text field of attachments. You can configure the middleware a notifier will use on initialization:
notifier = Slack::Notifier.new "WEBHOOK_URL" do
middleware format_message: { formats: [:html] }
end
# this example will *only* use the format_message middleware and only format :html links
notifier.post text: "Hello <a href='http://example.com'>world</a>! [visit this](http://example.com)"
# => will post "Hello <http://example.com|world>! [visit this](http://example.com)"The middleware can be set with a their name, or by name and options. They will be triggered in order.
notifier = Slack::Notifier.new "WEBHOOK_URL" do
middleware :format_message, :format_attachments
end
# will run format_message then format_attachments with default options
notifier = Slack::Notifier.new "WEBHOOK_URL" do
middleware format_message: { formats: [:html] },
format_attachments: { formats: [:markdown] }
end
# will run format_message w/ formats [:html] then format_attachments with formats [:markdown]Available middleware:
format_message
This middleware takes the :text key of the payload and runs it through the Linkformatter. You can configure which link formats to look for with a :formats option. You can set [:html] (only html links), [:markdown] (only markdown links) or [:html, :markdown] (the default, will format both).
format_attachments
This middleware takes the :text key of any attachment and runs it through the Linkformatter. You can configure which link formats to look for with a :formats option. You can set [:html] (only html links), [:markdown] (only markdown links) or [:html, :markdown] (the default, will format both).
at
This simplifies the process of notifying users and rooms to messages. By adding an :at key to the payload w/ an array of symbols the appropriately formatted commands will be prepended to the message. It will accept a single name, or an array.
For example:
notifier.post text: "hello", at: :casper
# => "<@casper> hello"
notifier.post text: "hello", at: [:here, :waldo]
# => "<!here> <@waldo> hello"channels
If the channel argument of a payload is an array this splits the payload to be posted to each channel.
For example:
notifier.post text: "hello", channel: ["default", "all_the_things"]
# => will post "hello" to the default and all_the_things channelTo send a message directly to a user, their username no longer works. Instead you'll need to get the user's ID and set that as the channel.
At the time of writing, one way to get a user's ID is to:
- go to their profile
- click ... ("More actions")
- click Copy Member ID
Middleware is fairly straightforward, it is any class that inherits from Slack::Notifier::PayloadMiddleware::Base and responds to #call. It will always be given the payload as a hash and should return the modified payload as a hash.
For example, lets say we want to replace words in every message, we could write a middleware like this:
class SwapWords < Slack::Notifier::PayloadMiddleware::Base
middleware_name :swap_words # this is the key we use when setting
# the middleware stack for a notifier
options pairs: ["hipchat" => "slack"] # the options takes a hash that will
# serve as the default if not given any
# when initialized
def call payload={}
return payload unless payload[:text] # noope if there is no message to work on
# not efficient, but it's an example :)
options[:pairs].each do |from, to|
payload[:text] = payload[:text].gsub from, to
end
payload # always return the payload from your middleware
end
end
notifier = Slack::Notifier.new "WEBHOOK_URL" do
middleware :swap_words # setting our stack w/ just defaults
end
notifier.ping "hipchat is awesome!"
# => pings slack with "slack is awesome!"
notifier = Slack::Notifier.new "WEBHOOK_URL" do
# here we set new options for the middleware
middleware swap_words: { pairs: ["hipchat" => "slack",
"awesome" => "really awesome"]}
end
notifier.ping "hipchat is awesome!"
# => pings slack with "slack is really awesome!"If your middleware returns an array, that will split the message into multiple pings. An example for pinging multiple channels:
class MultiChannel < Slack::Notifier::PayloadMiddleware::Base
middleware_name :channels
def call payload={}
return payload unless payload[:channel].respond_to?(:to_ary)
payload[:channel].to_ary.map do |channel|
pld = payload.dup
pld[:channel] = channel
pld
end
end
endSince version 1.0 has been released, the aim is to follow Semantic Versioning as much as possible. However, it is encouraged to check the changelog when updating to see what changes have been made.
To summarize the reasoning for versioning:
Given a version number MAJOR.MINOR.PATCH, increment:
- MAJOR version when incompatible API changes are made
- MINOR version for adding functionality in a backwards-compatible manner or bug fixes that *may* change behavior
- PATCH version for make backwards-compatible bug fixes
$ rspecThere is also an integration test setup to just double check pinging across the supported rubies. To run:
- Copy the
.env-examplefile to.envand replace with your details. - Make sure
bin/testis executable - then run and watch for the pings in your slack room
$ bin/testIf there is any thing you'd like to contribute or fix, please:
- Fork the repo
- Add tests for any new functionality
- Make your changes
- Verify all new & existing tests pass
- Make a pull request
The slack-notifier gem is distributed under the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent