Managing Scopes

Overview

slackteams uses incoming webhook tokens to interact with the Slack API. There are two main methods to create a token.

1. Use slackteams::add_team_interactive to interactively create a token for the R session.
2. BYOT (Bring your own token) You are a super user or work at a company that supplied you a token.

Each has their own pros and cons depending on what type of usage you may have

Token Type	User Level	Session Persistent	Manage Multiple Teams in Session	Store Credentials Locally	Depend on External Server
Interactive	All	No	Yes	No	No
BYOT	Intermediate	Yes	No	Yes	No

Interactive

This is similar to oauth2 implementation you would see in googlesheets4. The steps are:

1. Call the function from the R console
2. Authorize the creation of the token in a browser.
3. Get redirected back to the R console.

This is by far the easiest method.

The main piece that the user controls are the permission scopes the token has attached to it. To help with this we use a yaml file to allow users to define locally what scopes they want to define. {slackteams} comes with its own yaml file with the scopes that are needed to use all of slackverse.

scopes

• channels: public channels in the workspace
• groups: private channels that your slack app has been added to
• users: people in the workspace
• im: direct messages that your slack app has been added to
• mpim: group direct messages that your slack app has been added to
• emoji: custom emoji in the workspace
• files: files shared in channels and conversations that your slack app has been added to
• usergroups: user groups in the workspace
• chat: messages in approved channels & conversations
• team: team metainformation

permissions

• write access mean that you can post content in a scope
• read access mean that you can view basic information about a scope
• history access mean that you can view messages and other content in a scope

The following yaml contains a base role which contains only read access permissions and slackverse role containing permissions needed for the packages in slackverse.

Click the triangle to view the scopes and the permission of each of these roles:

Scopes

base:
  - channels:
    - read
  - users:
    - read
  - groups:
    - read
  - mpim:
    - read
  - im:
    - read
  - team:
    - read

slackverse:
  - channels:
    - history
    - read
    - write
  - users:
    - read
  - groups:
    - history
    - read
    - write
  - mpim:
    - history
    - read
    - write
  - im:
    - history
    - read
    - write
  - usergroups:
    - read
  - chat:
    - write
  - emoji:
    - read
  - files:
    - read
    - write
  - team:
    - read

The default scope is called by

slackteams::add_team_interactive(
  scopes = load_scopes(
    system.file("scopes.yml", package = "slackteams"),
    "base"
  )
)

and corresponds to

slackteams::add_team_interactive(scopes = load_scopes())

To use the slackverse role, use

slackteams::add_team_interactive(which = "slackverse"))

It is also possible to define custom roles. To do this, define a scopes file, for example “custom_scopes.yml”, which should have scopes defined following the Slack permission scopes. For example

{details,details.lang = 'yml',details.summary = 'Custom Scopes',echo= FALSE}` base: - channels: - read - users: - read - groups: - read - mpim: - read - im: - read - team: - read analyze: - channels: - read - history - users: - read - groups: - read - history - mpim: - read - im: - read - history - team: - read - links: - read postanalysis: - channels: - read - users: - read - groups: - read - mpim: - read - im: - write - team: - read

The resulting file can then be used, for example as

slackteams::add_team_interactive(
  scopes = load_scopes("/path/to/custom_scopes.yml", which = "analyze")
)

BYOT

This is useful if you:

• Have a token that is maintained by your work slack team
• Are an expert user and have your own incoming webhook that you maintain.