-
Notifications
You must be signed in to change notification settings - Fork 84
/
Copy pathREADME.Rmd
137 lines (92 loc) · 5.44 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
---
output: rmarkdown::github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r base, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# slackr <a href="https://matthewrkaye.com/slackr"><img src="man/figures/logo.png" align="right" height="138" alt = ""/></a>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=slackr)
[](https://github.com/mrkaye97/slackr/actions/workflows/R-CMD-check.yaml)
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://codecov.io/gh/mrkaye97/slackr)
<!-- 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
```{r setup, eval=FALSE}
# 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](https://matthewrkaye.com/slackr/news/index.html) 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:
* Option 1 setup: `vignette('scoped-bot-setup', package = 'slackr')`
* Option 2 setup: `vignette('webhook-setup', package = 'slackr')`
* Usage: `vignette('using-slackr', package = 'slackr')`
**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:
- [Bob Rudis](https://github.com/hrbrmstr)
- [Jay Jacobs](https://github.com/jayjacobs)
- [David Severski](https://github.com/davidski)
- [Quinn Weber](https://github.com/qsweber)
- [Konrad Karczewski](https://github.com/konradjk)
- [Ed Niles](https://github.com/eniles)
- [Rick Saporta](https://github.com/rsaporta)
- [Jonathan Sidi](https://github.com/yonicd)
- [Matt Kaye](https://github.com/mrkaye97)
- [Xinye Li](https://github.com/xinye1)
- [Andrie de Vries](https://github.com/andrie)
for their contributions to the package!
## Known Issues
* Depending on your scopes, `slackr` could quietly fail (i.e. not throw an error, but also not post anything to your channel). If this happens, try explicitly adding the app you're trying to have `slackr` post as to the channel you want in your Slack workspace with `/invite @your_app_name` or make sure you have `chat:write.public` enabled.