Getting Started with SlackTools!

This document should get you started with SlackTools in three easy steps

Step 1: Installing slackTools

There are a couple ways to install slackTools using pip

pip install via HTTPS:

python -m pip install --upgrade git+https://github.com/THIS_GIT_REPO.git@OPTIONAL_BRANCH_NAME

If not specifying a branch, omit @OPTIONAL_BRANCH_NAME

pip install via SSH:

python -m pip install --upgrade git+ssh://git@github.com/THIS_GIT_REPO.git@OPTIONAL_BRANCH_NAME

If not specifying a branch, omit @OPTIONAL_BRANCH_NAME

OR (if you want/already have a local clone)

pip install via local clone:

git clone https://github.com/THIS_GIT_REPO.git
python -m pip install --upgrade -e slackTools

STEP 2: Configure your SLACK KEY

• This is done by creating the file slack.key.toml. For a template of this file, please see template.slack.key.toml
  
• When search for slack keys, SlackTools searches the following locations:
  • 1st: The filepath provided at initialization
  • 2nd: Default storage locations:
    • Locally, under the filename slack.key.toml or hidden filename .slack.key.toml
    • Globally, in home directory under ~/.slack/slack.key.toml

If you are going to use SlackTools a lot, across several projects, and/or don't want to pollute your git repo, make the key global and place the file in ~/.slack/slack.key.toml.

What keys do I need?

You need a webhook key (easy) or a bot Token (slightly harder, but can post messages and files to pretty much anywhere).

Token	text	mrkdwn	files/images	blocks	to any user	to any channel
Webhook	✅	✅	❌	✅	❌	❌
Bot	✅	✅	✅	✅	✅	✅

For webhook tokens, see: https://api.slack.com/messaging/webhooks
For bot tokens, see: https://api.slack.com/authentication/basics

Notifications and Channels

The limit the scope of permissions available to SlackTools, automatic searching and conversion of usernames and channels to slack IDs is not supported. That being said, your slack.key.toml works as a lookup table and slack IDs are easy to find in the profile info of a user and the about of a channel.

• For notifying users, SlacksTools converts any reference like @yourName to the corresponding ID (ex: <@UNGCTYRUHJ>) of each user.
  • Note! Only works with mrkdwn enabled fields (e.g. send_markdown()).
• For channels, SlacksTools converts destination channel_name yourChannel to the corresponding ID (ex: CNGCTYRJ8G) when you perform an action (e.g. send_message()).
  • Note, with webhooks, this is done through the webhook_token parameter. With bot tokens, this is done through the channel_id parameter.

Step 3: Start using SlackTools!

Here are some examples:

Using a webhook:

import slackTools as sT
slack = sT.SlackTools_webhook()
slack = SlackTools_webhook(filepath_slack_keys="slack.key.toml")

# Text examples:
slack.msg("I am a cat")
slack.send_message("Hello world message!!")

# mrkdwn examples:
slack.write("I am a __whale__")
slack.send_markdown("@you your **experiment** is done", channel_id="RESEARCH")

Using a bot token

import slackTools as sT
slack = sT.SlackTools_bot()
slack = SlackTools_bot(filepath_slack_keys="slack.key.toml")

# Text examples:
slack.msg("I am a cat")
slack.send_message("Hello world message!!")

# mrkdwn examples:
slack.write("I am a __whale__")
slack.send_markdown("@you your **experiment** is done", channel_id="RESEARCH")

# File upload example:
slack.write("I am a __whale__")
slack.send_markdown("@you your **experiment** is done", channel_id="RESEARCH")

Notes 1: How do I learn mrkdwn and Slack's Block Kit?

See https://api.slack.com/reference/block-kit/blocks#image
See https://api.slack.com/messaging/composing/layouts#when-to-use-attachments

Notes 2: Required Authentication Scopes

With webhooks, the permission scope incoming-webhook is added automatically and therefore no permission scopes need to be set. With bot tokens, the following scopes may be required:

Required Scope	activity
chat:write	Send messages
im:write	Start direct messages with people
mpim:write	Start group direct messages with people
files:write	Upload, edit, and delete files

Notes 3: Uninstalling SlackTools

python -m pip uninstall slackTools