From 04866dad70926294b42a7aa1290525e1561f0eef Mon Sep 17 00:00:00 2001 From: Sijis Aviles Date: Thu, 22 Jul 2021 00:52:10 -0500 Subject: [PATCH 1/2] docs: Add notes about required scopes --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index cc5c720..533dd37 100644 --- a/README.md +++ b/README.md @@ -71,3 +71,10 @@ How to set up such an architecture is outside the scope of this readme and is le ### Current token with Events Socket-mode client Create a current bot token, enable socket mode. Configure errbot to use the bot and app tokens and start using Slack. Read [this document](https://github.com/slackapi/python-slack-sdk/blob/main/docs-src/socket-mode/index.rst) for instructions on setting up Socket-mode. + +Ensure the bot is also subscrbed to the following events: +* `file_created` +* `file_public` +* `message.channels` +* `message.groups` +* `message.im` From 9bc00d85a68c3f4996b4fbf5dccc4ae8119ef6d7 Mon Sep 17 00:00:00 2001 From: Sijis Aviles Date: Thu, 22 Jul 2021 01:08:18 -0500 Subject: [PATCH 2/2] style: format README --- README.md | 79 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 533dd37..737735a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # err-backend-slackv3 + Slack Events and Real Time Messaging backend for Errbot ## Purpose @@ -11,12 +12,13 @@ feedback to happen on independent release cycles. It is the hope and intention of the authors that this backend will eventually be incorporated as part of the official errbot project. -## Connection methods +## Connection Methods Slack has been making changes to their OAuth and API architecture that can seem quite confusing. No matter which OAuth bot token you're using or the API architecture in your environment, slackv3 has got you covered. The backend will automatically detect which token and architecture you have and start listening for Slack events in the right way: + - Legacy tokens (OAuthv1) with Real Time Messaging (RTM) API - Current token (OAuthv2) with Event API using the Event Subscriptions and Request URL. - Current token (Oauthv2) with Event API using the Socket-mode client. @@ -27,54 +29,67 @@ These instructions are for errbot running inside a Python virtual environment. The virtual environment is created in `/opt/errbot/virtualenv` and errbot initialised in `/opt/errbot`. The extra backend directory is in `/opt/erbot/backend`. 1. Create the errbot virtual environment - ``` - mkdir -p /opt/errbot/backend - virtualenv --python=python3 /opt/errbot/virtualenv - ``` + + ```python + mkdir -p /opt/errbot/backend + virtualenv --python=python3 /opt/errbot/virtualenv + ``` + 2. Install and initialise errbot. [See here for details](https://errbot.readthedocs.io/en/latest/user_guide/setup.html) - ``` - source /opt/errbot/virtualenv/bin/activate - pip install errbot - cd /opt/errbot - errbot --init - ``` + + ```python + source /opt/errbot/virtualenv/bin/activate + pip install errbot + cd /opt/errbot + errbot --init + ``` + 3. Configure the slackv3 backend and extra backend directory. Located in `/opt/errbot/config.py` - ``` - BACKEND="SlackV3" - BOT_EXTRA_BACKEND_DIR=/opt/errbot/backend - ``` + + ```python + BACKEND="SlackV3" + BOT_EXTRA_BACKEND_DIR=/opt/errbot/backend + ``` + 4. Clone `err-backend-slackv3` into the backend directory and install module dependencies. - ``` - cd /opt/errbot/backend - git clone https://github.com/errbotio/err-backend-slackv3 - pip install -r /opt/errbot/backend/err-backend-slackv3/requirements.txt - ``` + + ```python + cd /opt/errbot/backend + git clone https://github.com/errbotio/err-backend-slackv3 + pip install -r /opt/errbot/backend/err-backend-slackv3/requirements.txt + ``` + 5. Configure the slack bot token, signing secret (Events API with Request URLs) and/or app token (Events API with Socket-mode). Located in `/opt/errbot/config.py` - ``` - BOT_IDENTITY = { - 'token': 'xoxb-...', - 'signing_secret': "", - 'app_token': "xapp-..." - } - ``` + + ```python + BOT_IDENTITY = { + 'token': 'xoxb-...', + 'signing_secret': "", + 'app_token': "xapp-..." + } + ``` ## Setting up Slack application ### Legacy token with RTM + This was the original method for connecting a bot to Slack. Create a bot token, configure errbot with it and start using Slack. Pay attention when reading [this document](https://github.com/slackapi/python-slack-sdk/blob/main/docs-src/real_time_messaging.rst) explaining how to create a "classic slack application". Slack does not allow Legacy bot tokens to use the Events API. ### Current token with Events Request URLs + This is by far the most complex method of having errbot communicate with Slack. The architecture involves server to client communication over HTTP. This means the Slack server must be able to reach errbot's `/slack/events` endpoint via the internet using a valid SSL connection. How to set up such an architecture is outside the scope of this readme and is left as an exercise for the reader. Read [this document](https://github.com/slackapi/python-slack-events-api) for details on how to configure the Slack app and request URL. ### Current token with Events Socket-mode client + Create a current bot token, enable socket mode. Configure errbot to use the bot and app tokens and start using Slack. Read [this document](https://github.com/slackapi/python-slack-sdk/blob/main/docs-src/socket-mode/index.rst) for instructions on setting up Socket-mode. Ensure the bot is also subscrbed to the following events: -* `file_created` -* `file_public` -* `message.channels` -* `message.groups` -* `message.im` + +- `file_created` +- `file_public` +- `message.channels` +- `message.groups` +- `message.im`