slack_builder

SlackBuilder

This gem aims to help generating Slack message payloads using Block-kit API with kind of comfortable Ruby DSL focused on readability ¯\(ツ)/¯

Available blocks

	Block type	Available fields
✅	actions	elements
✅	context	elements
✅	divider	N/A
❌	file
✅	header	text
🏗️	image	image_url, alt_text, title
❌	input
✅	rich_text	elements
✅	section	text, fields, accessory
🏗	video	video_url, thumbnail_url, alt_text, title

Rich Text blocks

	Block type	Available fields
✅	rich_text_section	elements
✅	rich_text_preformatted	elements
✅	rich_text_quote	elements
✅	rich_text_list	elements, style, indent, offset

Rich Text elements

	Block type	Available fields
✅	broadcast	range
✅	channel	channel_id, style
✅	color	value
✅	date	timestamp, format, url, fallback
✅	emoji	name
✅	link	text, url, unsafe, style
✅	text	text, style
✅	user	user_id, style
✅	usergroup	usergroup_id, style

Interactive elements

	Block type	Available fields
🏗	button	text, url, action_id, style, accessibility_label

Installation

[!WARNING] Gem is going to be released on RubyGems soon.

Until the first release, you can install it from the Github repository using the main branch.

gem 'slack_builder', git: 'https://github.com/cyb-/slack-builder.git', branch: 'main', require: false

Usage

Please refer to the Slack API Block-kit documentation for available blocks and options.

require 'slack_builder'

SlackBuilder.message do
  header 'Hello world :wave:'
  divider
  context do
    mrkdwn '*`Hello`* <https://example.com|world> :wave:'
  end
  image 'https://media.giphy.com/media/AcfTF7tyikWyroP0x7/giphy.gif', alt_text: 'Foo', title: 'Blob :ok_hand:', emoji: false
  divider
  section '*`Hello`* <https://example.com|world> :wave:' do
    mrkdwn '*Priority*'
    mrkdwn '*Critical*'
    plain_text 'High :collision:'
    plain_text '¯\\_(ツ)_/¯', emoji: false
    accessory do
      image 'https://media.giphy.com/media/cYNjbM2MvPzM8raKvh/giphy.gif', alt_text: 'Bar'
    end
  end
  video 'https://www.youtube.com/watch?v=PdaAHMztNVE', thumbnail_url: 'https://media.giphy.com/media/cYNjbM2MvPzM8raKvh/giphy.gif', alt_text: 'Foo', title: 'Bar :collision:'
  divider
  rich_text do
    section do
      text 'Hello', bold: true, code: true
      link 'world', url: 'https://example.com'
      emoji :wave
    end
    quote do
      text 'Woopsie'
      broadcast :channel
      color '#666'
    end
    list :bullet do
      section do
        usergroup SLACK_USERGROUP_ID, client_highlight: true, highlight: true, italic: true
      end
      section do
        channel SLACK_CHANNEL_ID, client_highlight: true, bold: true, strike: true
        date 42, format: '{day_divider_pretty}', url: 'https://example.com'
      end
    end
    list :ordered, indent: 1 do
      section do
        text 'Hello'
      end
      section do
        text 'world'
      end
    end
    list :bullet do
      section do
        emoji :wave
      end
    end
    preformatted do
      text 'Hello', italic: true
      user SLACK_USER_ID, unlink: true, highlight: true, bold: true
    end
  end
  divider
  actions do
    button 'Click me :bomb:', url: 'https://github.com/cyb-/slack-builder', style: :danger
  end
end

You can also optionally add secondary attachments to your message, with an optional color

require 'slack_builder'

SlackBuilder.message do
  header 'Hello world :wave:'
  
  attachment color: '#666' do
    rich_text do
      section do
        text 'Woopsie'
        emoji :grimacing
      end
    end
  end
end

Or with a text

require 'slack_builder'

SlackBuilder.message '*`Hello`* <https://example.com|world> :wave:' do
  header 'Hello world :wave:'
  
  attachment do
    rich_text do
      section do
        emoji :bomb
      end
    end
  end
end

Sending message

[!NOTE] Gem has no dependencies, it's up to you to send the message however you want ¯\(ツ)/¯

Example using Slack client

require 'slack_builder'

payload = SlackBuilder.message do
  # ...
end
  
client = Slack::Web::Client.new
client.chat_postMessage(channel: '#somewhere', as_user: true, **payload)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cyb-/slack-builder/issues.

License

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