Home

Awesome

Note: slackr is seeking a new maintainer! Please see this issue

<!-- README.md is generated from README.Rmd. Please edit that file -->

slackr <a href="https://matthewrkaye.com/slackr"><img src="man/figures/logo.png" align="right" height="138" alt = ""/></a>

<!-- badges: start -->

CRAN status R-CMD-check Lifecycle: experimental codecov

<!-- badges: end -->

slackr provides a set of tools for making it easier to send messages, data, alerts, etc. directly from R to Slack. You can use this package to send well-formatted output from R to all teammates (or to specific individuals) at the same time with little effort. You can send text, R function output, images from the current graphics device and ggplots, R objects (as R data files), rendered LaTeX expressions, and uploaded files.

Installation

# CRAN version
install.packages("slackr")

# Development version
devtools::install_github("mrkaye97/slackr")

Breaking Changes

Version 3.0.0+ removes all references to bot_user_oauth_token (deprecated in v2.4.0) in favor of token. There have also been significant changes to how slackr and slackr_bot handle errors. See the changelog for more details.

Version 2.4.0+ now allows users to choose between using a bot token and a user token. See below for details and check the changelog (NEWS.md) for more changes.

Setup

There are three ways of interfacing with slackr that provide significantly different functionality:

  1. Creating a single-channel bot

    Using only a webhook to send messages to a channel

  2. Creating a fully-functional multi-channel bot

    Creating a bot user to send messages to multiple channels, including plots, tables, files, etc. as well as deleting messages, reading the channels in a workspace, etc.

  3. Using a user token to send messages from a specific user’s account

    Similar to the fully-scoped bot token, but connected to the account of a single user. This approach is not recommended in production settings – or any settings where a token needs to be shared – but it can be useful for one-off Slack messages as it lets users send data as themselves as opposed to through a bot.

In most cases, we recommend Option 1 above. This requires the fewest permissions and is the simplest to set up, and will allow basic messaging to a specific channel.

See the vignettes for setup instructions.

Vignettes

The vignettes contain setup instructions and example usage:

Important Note: The setup process for Option 2 and Option 3 are roughly the same, with only slightly differing scopes.

Config File Setup

The slackr_setup() function will try to read setup values from a ~/.slackr (you can change the default filepath by recording in the SLACKR_CONFIG_FILE_PATH environment variable or supplying as an argument to the config_file parameter) configuration file, which may be easier and more secure than passing them in manually (plus, will allow you to have multiple slackr configurations for multiple Slack.com teams).

The file is in Debian Control File (DCF) format since it really doesn’t need to be JSON and R has a handy read.dcf() function since that’s what DESCRIPTION files are coded in.

Here’s the basic format for the configuration file:

token: xox*-<your app's token>
channel: #general
username: slackr
incoming_webhook_url: https://hooks.slack.com/services/XXXXX/XXXXX/XXXXX
icon_emoji: 'boom'

As of slackr 2.3.0, you can create a config file with create_config_file() instead of setting it up manually. See the docs for details.

You can also change the default emoji icon (from the one you setup at integration creation time) with icon_emoji.

Contributors

Many thanks to:

for their contributions to the package!

Known Issues