🎃 Hacktoberfest 🎃

All the details you need before participating with us during Hacktoberfest.

OperationCode-Pybot

OperationCode PyBot is a Python Slack Bot extending Pyslacker's sir-bot-a-lot framework.

Resources

Contributing

Bug reports and pull requests are welcome on Github. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. If you wish to assist, join the #oc-python-projects rewrite to learn how to contribute.

Quick Start

Recommended versions of tools used within the repo:

[email protected] or greater (in some environments, you may need to specify version of python i.e. python test.py vs python3 test.py))
[email protected] or greater
[email protected] or greater
- Poetry is a packaging and dependency manager, similar to pip or pipenv
- Poetry provides a custom installer that can be ran via curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
- Alternatively, poetry can be installed via pip/pip3 with pip install --user poetry or pip3 install --user poetry
- See https://poetry.eustace.io/docs/

# Install dependencies (ensure poetry is already installed)
poetry install

# Run local development
poetry run python -m pybot

# Run testing suite
poetry run pytest

# Run formatting and linting
poetry run black .
# the next line shouldn't output anything to the terminal if it passes
poetry run flake8
poetry run isort -rc .

How to Test Integration With Slack

After having developed some new feature, or having in hand what you believe is a fix for an existing bug, how do you test it out in a real system in order to make sure that your changes do all that you hope they do? The answer; bring up the application in your own environment and hook it up to Slack!

In order to do this, you'll want to tackle the following items in order:

Setup your own Slack workspace.
Grab a signing secret from Slack that pybot can utilize.
Launch pybot locally, passing it your Slack signing secret.
Attach your pybot instance to the public internet so that Slack can speak with it.
Point Slack at your running pybot instance, and properly configure it.

The following sections will guide you through each of these stages.

1 - Setup Your Own Slack Workspace

To start, you'll want to visit Slack's Getting Started page. From this page, follow the steps required to create a new workspace. The names/options you configure during creation don't matter so much, but make sure you associate it with an email address you have access to. Once complete it should present you with an option to login to the new workspace, make sure you go ahead and do that.

If you're having a hard time figuring this out, try checking out the following Slack article Create a Slack Workspace.

Create expected channels

Several of Pybot's features involve sending messages to specific channels - in order for this to work in your personal Slack workspace you'll need to create the following channels:

mentors-internal
greetings
moderators
oc-tech

2 - Create a pybot App in Your Slack Workspace

The next step is to create a new bot application in your workspace. While still logged in, visit the App Management page and choose to create a new app. During this process, make sure to copy down the signing secret key that gets generated for your app, as you'll need it later, following this, follow the guidelines for creating a bot app as laid out in the Enabling interactions with bots article. When you get to the stage of creating the bot user, make sure to write down the bot user OAuth access token that is presented, as you'll need to use it later.

On the OAuth & Permissions page configure the Pybot app with the following scopes

channels:manage
chat:write
chat:write.public
commands
users:read

3 - Launch pybot Locally, Passing in Your Signing Secret

With your Slack workspace, app and bot user created, and your app signing secret and bot user OAuth access token in hand, you should now be ready to configure pybot to integrate with your new Slack workspace. To do this, you'll first want to setup the proper configuration in pybot.

pybot configuration is specified completely through environment variables. When running locally, you can configure the ./docker/pybot.env file with the environment variable name/value pairings, which will get evaluated on application start. Otherwise, make sure to export or pass in the correct environment variables through your shell when launching pybot.

Here's an example of configuring these through the pybot.env file:

SLACK_BOT_SIGNING_SECRET=APP-SIGNING-SECRET
BOT_USER_OAUTH_ACCESS_TOKEN=BOT-USER-OAUTH-TOKEN

NOTE: More configuration settings than these may be specified. Please see the Known Configuration Settings section near the bottom of this document for details on other settings that can be set.

4 - Attach Your pybot Instance to the Public Internet

With an instance of pybot running, you now need to expose this instance to the public internet so Slack can send in API requests. You can easily utilize ngrok for this purpose if you wish. To do so; download ngrok from https://ngrok.com/download and set up a tunnel like so:

ngrok http 5000

Pay attention to copy out the response you get and keep this command running. Here's an example output from the command:

ngrok by @inconshreveable                                                                        (Ctrl+C to quit)
Session Status                online                                                                             
Session Expires               7 hours, 56 minutes                                                                
Version                       2.3.35                                                                             
Region                        United States (us)                                                                 
Web Interface                 http://127.0.0.1:4040                                                              
Forwarding                    http://9d73595a7aac.ngrok.io -> http://localhost:5000                              
Forwarding                    https://9d73595a7aac.ngrok.io -> http://localhost:5000                             
Connections                   ttl     opn     rt1     rt5     p50     p90                                        
                              0       1       0.00    0.00    0.00    0.00                                       
HTTP Requests

With this done, ngrok will now expose the instance of pybot running locally on port 5000 via the "Forwarding" address it returns. Be sure to use the URL beginning with https.

5 - Point Slack at Your Running pybot Instance

With the initial Slack configuration complete and your instance of pybot running on the public internet, it is now the perfect time to fully configure Slack to interact with your bot. Depending on the interactions you're wanting to play with, there are various configurations you can specify, which can be broken down into the following parts:

Event Subscriptions - this allows pybot to respond to various events that may occur in your Slack workspace.
Slash Commands - this allows a user to invoke various commands from any channel in your workspace to interact with pybot.
Interactive Components - this allows various options to be exposed when right clicking on a message, or, when the bot presents various user elements that can be interacted with, instructs Slack on where to send the results for such interactions.

High level steps for configuring each of these can be found in the following sub-sections; note that you don't need to necessarily configure all of these, it all depends on what areas of pybot you're wanting to play with.

Event Subscriptions

You can follow the instructions (and read helpful related information) on the Events API page on Slack to setup event subscriptions. When configuring your events URI; make sure you pass in the Base-URI that pybot is listening on followed by the text /slack/events. For example:

https://123_random_code_321.ngrok.io/slack/events

Slash Commands

You can follow the instructions (and read helpful relation information) on the Enabling interactivity with Slash Commands page on Slack to setup pybot slash commands. When configuring a Slash command, make sure you configure the request URL to match the Base-URI that pybot is listening on followed by the text /slack/commands. For example:

https://123_random_code_321.ngrok.io/slack/commands

You'll use the same URI for each command. Here's a table listing of currently supported commands along with some suggested configuration text:

Command	Description	Usage Hint
/lunch	find lunch suggestions nearby	<zip code> <distance in miles>
/mentor	request mentoring
/mentor-volunteer	offer to mentor others
/repeat	parrot canned messages	<10000
/report	report something to the admins
/roll	roll x dice with y sides
/ticket	submit ticket to admins	(text of ticket)

👋 IMPORTANT!

The /lunch command requires a valid Yelp API token stored in the YELP_TOKEN environment variable. See https://www.yelp.com/developers/faq

Similarly, the /mentor and /mentor-volunteer commands require access to an Airtable environment with a specific configuration. If you're planning on working with the mentor functionality please reach out to the #oc-python-projects channel for help getting set up.

Interactive Components

You can follow the instructions (and read helpful related information) on the Handling user interaction in your Slack apps page on Slack to setup Slack interactive component configuration. When configuring the request URL, you'll want to set it to the Base-URI that pybot is listening on followed by the text /slack/actions. For example:

https://123_random_code_321.ngrok.io/slack/actions

You'll also want to make sure to configure the report message action with the following parameters:

Name	Description	Callback ID
Report Message	Report this message to admins	report_message

Known Configuration Settings

This application has a number of environment variables that can be set when launching to alter the behaviour of the application. The list below is an incomplete description of a number of them. Please feel free to update this list with more details via a PR:

Name	Description	Example
SLACK_BOT_SIGNING_SECRET	The unique signing secret used by Slack for a specific app that will be validated by pybot when inspecting an inbound API request	f3b4d774b79e0fb55af624c3f376d5b4
BOT_USER_OAUTH_ACCESS_TOKEN	The bot user specific OAuth token used to authenticate the bot when making API requests to Slack	xoxb-800506043194-810119867738-vRvgSc3rslDUgQakFbMy3wAt

License

This package is available as open source under the terms of the MIT License.

ptrstr / operationcode-pybot Goto Github PK

operationcode-pybot's Introduction