{"id":19827955,"url":"https://github.com/operationcode/operationcode-pybot","last_synced_at":"2025-07-08T12:34:01.297Z","repository":{"id":33239299,"uuid":"146210805","full_name":"OperationCode/operationcode-pybot","owner":"OperationCode","description":"Operation Code's Official Slackbot","archived":false,"fork":false,"pushed_at":"2024-04-03T15:55:44.000Z","size":9409,"stargazers_count":31,"open_issues_count":17,"forks_count":45,"subscribers_count":8,"default_branch":"staging","last_synced_at":"2024-10-30T19:25:22.965Z","etag":null,"topics":["hacktoberfest","hacktoberfest2017","hacktoberfest2018","hacktoberfest2019","hacktoberfest2020","python","slack-api","slackbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OperationCode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.MD","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-08-26T19:39:25.000Z","updated_at":"2024-05-17T16:47:51.000Z","dependencies_parsed_at":"2023-12-17T18:36:58.990Z","dependency_job_id":null,"html_url":"https://github.com/OperationCode/operationcode-pybot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperationCode%2Foperationcode-pybot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperationCode%2Foperationcode-pybot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperationCode%2Foperationcode-pybot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperationCode%2Foperationcode-pybot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OperationCode","download_url":"https://codeload.github.com/OperationCode/operationcode-pybot/tar.gz/refs/heads/staging","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224261984,"owners_count":17282267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","hacktoberfest2017","hacktoberfest2018","hacktoberfest2019","hacktoberfest2020","python","slack-api","slackbot"],"created_at":"2024-11-12T11:14:32.994Z","updated_at":"2024-11-12T11:14:33.687Z","avatar_url":"https://github.com/OperationCode.png","language":"Python","readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Twitter Follow](https://img.shields.io/twitter/follow/operation_code.svg?style=social\u0026label=Follow\u0026style=social)](https://twitter.com/operation_code)\n[![Code-style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://contributor-covenant.org/)\n\n# OperationCode-Pybot\n\nOperationCode PyBot is a Python [Slack](https://api.slack.com) Bot utilizing [Slack Bolt](https://github.com/SlackAPI/bolt-python).\n\n## Resources\n* [Slack Web API Methods](https://api.slack.com/methods) - used to interact with Slack beyond the built-in Slack Bolt capabilities\n* [Slack Block Kit](https://api.slack.com/block-kit) - used to build the blocks used in various requests and responses\n* [Slack Bolt](https://slack.dev/bolt-python/tutorial/getting-started) - the underlying framework of the bot\n* [Slack Bolt API Reference](https://slack.dev/bolt-python/api-docs/slack_bolt/index.html)\n* [Slack Python SDK API Reference](https://slack.dev/python-slack-sdk/api-docs/slack_sdk/index.html)\n\n\n## Contributing\n[Bug reports](https://github.com/OperationCode/operationcode-pybot/issues) and [pull requests](https://github.com/OperationCode/operationcode-pybot/pulls) are welcome on [our Github repo](https://github.com/OperationCode/operationcode-pybot).\nThis project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\nThe best place to get assistance with OperationCode-Pybot is on [Slack](https://operationcode.org/join) in the `#oc-python-project` channel.\n\n## Quick Start\nRecommended versions of tools used within the repo:\n- `python@3.10` or greater\n- `pipenv@2021.5.29` or greater - [pipenv](https://github.com/pypa/pipenv) is a package manager similar to poetry that utilizes `pip` to manage project dependencies, along with creating new virtual environments\nand deterministic builds\n\n```bash\n# Ensure you have pipenv already installed\npipenv install --dev\n\n# Start up your virtual environment\npipenv shell\n\n# Run the test suite\npytest\n\n# Run the code formatter\nblack .\n```\n\n## How to Test Integration with SlackAPI\n\nIn order to test the new methods and interactions you may have created already,\nyou'll need an \"app configuration token\". In order to get one of those, you'll need to create [a new\nissue](https://github.com/OperationCode/operationcode-pybot/issues). Please use the `type: config token request`\nlabel and make the title \"\u003cYour Name\u003e Requests an App Config Token\". For example: `Judson Stevens Requests an App Config Token`.\n\nOnce you have created your issue, one of the maintainers of this repository will get in touch and give you your token.\n\n\n## How to Test Integration With Slack\n\nAfter having developed some new feature, or having in hand what you believe is\na fix for an existing bug, how do you test it out in a real system in order to\nmake sure that your changes do all that you hope they do? The answer; bring up\nthe application in your own environment and hook it up to Slack!\n\nIn order to do this, you'll want to tackle the following items in order:\n\n1. Setup your own Slack workspace.\n2. Grab a signing secret from Slack that pybot can utilize.\n3. Launch pybot locally, passing it your Slack signing secret.\n4. Attach your pybot instance to the public internet so that Slack can speak\n   with it.\n5. Point Slack at your running pybot instance, and properly configure it.\n\nThe following sections will guide you through each of these stages.\n\n### 1 - Setup Your Own Slack Workspace\n\nTo start, you'll want to visit Slack's [Getting\nStarted](https://slack.com/get-started) page. From this page, follow the steps\nrequired to create a new workspace. The names/options you configure during\ncreation don't matter so much, but make sure you associate it with an email\naddress you have access to. Once complete it should present you with an option\nto login to the new workspace, make sure you go ahead and do that.\n\nIf you're having a hard time figuring this out, try checking out the following\nSlack article [Create a Slack Workspace](https://slack.com/intl/en-ca/help/articles/206845317-Create-a-Slack-workspace).\n\n#### Create expected channels\nSeveral of Pybot's features involve sending messages to specific channels - in order\nfor this to work in your personal Slack workspace you'll need to create the following channels:\n- mentors-internal\n- greetings\n- moderators\n- oc-tech\n\n\n### 2 - Create a pybot App in Your Slack Workspace\n\nThe next step is to create a new bot application in your workspace. While still\nlogged in, visit the [App Management](https://api.slack.com/apps) page and\nchoose to create a new app. During this process, make sure to copy down the\nsigning secret key that gets generated for your app, as you'll need it later,\nfollowing this, follow the guidelines for creating a bot app as laid out in the\n[Enabling interactions with bots](https://api.slack.com/bot-users) article. When\nyou get to the stage of creating the bot user, make sure to write down the bot\nuser OAuth access token that is presented, as you'll need to use it later.\n\nOn the `OAuth \u0026 Permissions` page configure the Pybot app with the following scopes\n\n- channels:manage\n- chat:write\n- chat:write.public\n- commands\n- users:read\n\n### 3 - Launch pybot Locally, Passing in Your Signing Secret\n\nWith your Slack workspace, app and bot user created, and your app signing secret\nand bot user OAuth access token in hand, you should now be ready to configure\npybot to integrate with your new Slack workspace. To do this, you'll first want\nto setup the proper configuration in pybot.\n\npybot configuration is specified completely through environment variables. When\nrunning locally, you can configure the _./docker/pybot.env_ file with the\nenvironment variable name/value pairings, which will get evaluated on\napplication start. Otherwise, make sure to export or pass in the correct\nenvironment variables through your shell when launching pybot.\n\nHere's an example of configuring these through the _pybot.env_ file:\n\n```bash\nSLACK_BOT_SIGNING_SECRET=APP-SIGNING-SECRET\nBOT_USER_OAUTH_ACCESS_TOKEN=BOT-USER-OAUTH-TOKEN\n```\n\n**NOTE**: More configuration settings than these may be specified. Please see\nthe _Known Configuration Settings_ section near the bottom of this document\nfor details on other settings that can be set.\n\n### 4 - Attach Your pybot Instance to the Public Internet\n\nWith an instance of pybot running, you now need to expose this instance to the\npublic internet so Slack can send in API requests. You can easily utilize ngrok\nfor this purpose if you wish. To do so; download ngrok from https://ngrok.com/download\nand set up a tunnel like so:\n\n```bash\nngrok http 5000\n```\n\nPay attention to copy out the response you get and keep this command running.\nHere's an example output from the command:\n\n```bash\nngrok by @inconshreveable                                                                        (Ctrl+C to quit)\nSession Status                online                                                                             \nSession Expires               7 hours, 56 minutes                                                                \nVersion                       2.3.35                                                                             \nRegion                        United States (us)                                                                 \nWeb Interface                 http://127.0.0.1:4040                                                              \nForwarding                    http://9d73595a7aac.ngrok.io -\u003e http://localhost:5000                              \nForwarding                    https://9d73595a7aac.ngrok.io -\u003e http://localhost:5000                             \nConnections                   ttl     opn     rt1     rt5     p50     p90                                        \n                              0       1       0.00    0.00    0.00    0.00                                       \nHTTP Requests \n```\n\nWith this done, ngrok will now expose the instance of pybot running locally\non port 5000 via the \"Forwarding\" address it returns.  Be sure to use the URL\nbeginning with http**s**.\n\n### 5 - Point Slack at Your Running pybot Instance\n\nWith the initial Slack configuration complete and your instance of pybot\nrunning on the public internet, it is now the perfect time to fully configure\nSlack to interact with your bot. Depending on the interactions you're wanting to\nplay with, there are various configurations you can specify, which can be\nbroken down into the following parts:\n\n*  Event Subscriptions - this allows pybot to respond to various events that may\n   occur in your Slack workspace.\n*  Slash Commands - this allows a user to invoke various commands from any\n   channel in your workspace to interact with pybot.\n*  Interactive Components - this allows various options to be exposed when\n   right clicking on a message, or, when the bot presents various user\n   elements that can be interacted with, instructs Slack on where to send the\n   results for such interactions.\n\nHigh level steps for configuring each of these can be found in the following\nsub-sections; note that you don't need to necessarily configure all of these,\nit all depends on what areas of pybot you're wanting to play with.\n\n#### Event Subscriptions\n\nYou can follow the instructions (and read helpful related information) on the\n[Events API](https://api.slack.com/events-api) page on Slack to setup event\nsubscriptions. When configuring your events URI; make sure you pass in the\nBase-URI that pybot is listening on followed by the text _/slack/events_. For\nexample:\n\n    https://123_random_code_321.ngrok.io/slack/events\n\nAdditional setup may be needed depending on the type of events pybot is subscribing to. \nFor example, in order to work on the app's functionality on a `team_join` event, you need to:\n\n* Add `team_join` to workspace event\n* Make sure `greetings` channel exists and ensure the app is invited to the channel\n* Add necessary OAuth scopes to the app e.g. `users:read`, `chat:write`, etc.\n\nIn the section which says \"Subscribe to events on behalf of users\", you must add the following events:\n\n| Event Name            | Required OAuth Scope         |\n|-----------------------|------------------------------|\n| member_joined_channel | channels:read or groups:read |\n| message.channels      | channels:history             |\n| message.groups        | groups:history               |\n| message.im            | im:history                   |\n| team_join             | users:read                   |\n\n#### Slash Commands\n\nYou can follow the instructions (and read helpful related information) on the\n[Enabling interactivity with Slash Commands](https://api.slack.com/interactivity/slash-commands)\npage on Slack to setup pybot slash commands. When configuring a Slash command,\nmake sure you configure the request URL to match the Base-URI that pybot is\nlistening on followed by the text _/slack/commands_. For example:\n\n    https://123_random_code_321.ngrok.io/slack/commands\n   \nYou'll use the same URI for each command. Here's a table listing of currently\nsupported commands along with some suggested configuration text:\n\n| Command           | Description                    | Usage Hint                           |\n|-------------------|--------------------------------|--------------------------------------|\n| /lunch            | find lunch suggestions nearby  | \u0026lt;zip code\u003e \u0026lt;distance in miles\u003e |\n| /mentor           | request mentoring              |                                      |\n| /mentor-volunteer | offer to mentor others         |                                      |\n| /repeat           | parrot canned messages         | \u0026lt;10000                            |ask|ldap|merge|firstpr|channels|resources\u003e\n| /report           | report something to the admins | \u003ctext of message\u003e                    |\n| /roll             | roll x dice with y sides       | \u003cXdY\u003e                                |\n| /ticket           | submit ticket to admins        | (text of ticket)                     |\n\n**👋 IMPORTANT!**\n\nThe `/lunch` command requires a valid Yelp API token stored in the `YELP_TOKEN` \nenvironment variable. See https://www.yelp.com/developers/faq\n\nSimilarly, the `/mentor` and `/mentor-volunteer` commands require access to an Airtable\nenvironment with a specific configuration.  If you're planning on working with the mentor\nfunctionality please reach out to the `#oc-python-projects` channel for help getting set up.  \n\n#### Interactive Components\n\nYou can follow the instructions (and read helpful related information) on the\n[Handling user interaction in your Slack apps](https://api.slack.com/interactivity/handling)\npage on Slack to setup Slack interactive component configuration. When\nconfiguring the request URL, you'll want to set it to the Base-URI that pybot\nis listening on followed by the text _/slack/actions_. For example:\n\n    https://123_random_code_321.ngrok.io/slack/actions\n\nYou'll also want to make sure to configure the report message action with the\nfollowing parameters:\n\n| Name           | Description                   | Callback ID    |\n|----------------|-------------------------------|----------------|\n| Report Message | Report this message to admins | report_message |\n\n## License\nThis package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n\n\n## Notes\nOption 1 - Create your own Slack workspace to use for testing.\nFollow [this guide](https://slack.dev/bolt-python/tutorial/getting-started-http)\n\n\nStart the application with WebSockets instead of HTTP for better development experience? Requires the use of the SLACK_APP_TOKEN.\nWould need to set an environment variable to determine if we were in development or staging/production.\n\nDatabase to store history of events or just use logging? Probably best to use a database to store history of requests and responses?\nEasier to track interactions that way. \n\nUtilizing FastAPI allows us to take advantage of things like Pydantic, inherent typing, models, and a better handler\nfor the HTTP requests themselves.\n\nUtilizing [FastAPI](https://fastapi.tiangolo.com/) and [Slack-Bolt](https://slack.dev/bolt-python/tutorial/getting-started-http).\n\nAll the interactive elements of this bot were built using the Slack [Block Kit Builder](https://app.slack.com/block-kit-builder/).\nThe example JSON for each interactive element can be found in the `modules/slack/blocks/block_kit_examples` folder.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperationcode%2Foperationcode-pybot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foperationcode%2Foperationcode-pybot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperationcode%2Foperationcode-pybot/lists"}