Slack Events API adapter for Python
===================================
.. image:: https://badge.fury.io/py/slackeventsapi.svg
:target: https://pypi.org/project/slackeventsapi/
.. image:: https://github.com/slackapi/python-slack-events-api/actions/workflows/ci-build.yml/badge.svg
:target: https://github.com/slackapi/python-slack-events-api/actions/workflows/ci-build.yml
.. image:: https://codecov.io/gh/slackapi/python-slack-events-api/branch/main/graph/badge.svg
:target: https://codecov.io/gh/slackapi/python-slack-events-api
The Slack Events Adapter is a Python-based solution to receive and parse events
from Slack’s Events API. This library uses an event emitter framework to allow
you to easily process Slack events by simply attaching functions
to event listeners.
This adapter enhances and simplifies Slack's Events API by incorporating useful best practices, patterns, and opportunities to abstract out common tasks.
💡 We wrote a `blog post which explains how`_ the Events API can help you, why we built these tools, and how you can use them to build production-ready Slack apps.
.. _blog post which explains how: https://medium.com/@SlackAPI/enhancing-slacks-events-api-7535827829ab
⚠️ Important Notice
---------------------
If you use this library for Events API handling, you may need to use threads for stable event acknowledgement. See https://github.com/slackapi/python-slack-events-api/issues/84 for details.
If you're looking for the best recommended library at this point, check Bolt for Python: https://github.com/slackapi/bolt-python
The framework covers not only Events API but also all the latest Slack Platform features.
🤖 Installation
----------------
.. code:: shell
pip install slackeventsapi
🤖 App Setup
--------------------
Before you can use the `Events API`_ you must
`create a Slack App`_, and turn on
`Event Subscriptions`_.
💡 When you add the Request URL to your app's Event Subscription settings,
Slack will send a request containing a `challenge` code to verify that your
server is alive. This package handles that URL Verification event for you, so
all you need to do is start the example app, start ngrok and configure your
URL accordingly.
✅ Once you have your `Request URL` verified, your app is ready to start
receiving Team Events.
🔑 Your server will begin receiving Events from Slack's Events API as soon as a
user has authorized your app.
🤖 Development workflow:
===========================
(1) Create a Slack app on https://api.slack.com/apps
(2) Add a `bot user` for your app
(3) Start the example app on your **Request URL** endpoint
(4) Start ngrok and copy the **HTTPS** URL
(5) Add your **Request URL** and subscribe your app to events
(6) Go to your ngrok URL (e.g. https://myapp12.ngrok.com/) and auth your app
**🎉 Once your app has been authorized, you will begin receiving Slack Events**
⚠️ Ngrok is a great tool for developing Slack apps, but we don't recommend using ngrok
for production apps.
🤖 Usage
----------
**⚠️ Keep your app's credentials safe!**
- For development, keep them in virtualenv variables.
- For production, use a secure data store.
- Never post your app's credentials to github.
.. code:: python
SLACK_SIGNING_SECRET = os.environ["SLACK_SIGNING_SECRET"]
Create a Slack Event Adapter for receiving actions via the Events API
-----------------------------------------------------------------------
**Using the built-in Flask server:**
.. code:: python
from slackeventsapi import SlackEventAdapter
slack_events_adapter = SlackEventAdapter(SLACK_SIGNING_SECRET, endpoint="/slack/events")
# Create an event listener for "reaction_added" events and print the emoji name
@slack_events_adapter.on("reaction_added")
def reaction_added(event_data):
emoji = event_data["event"]["reaction"]
print(emoji)
# Start the server on port 3000
slack_events_adapter.start(port=3000)
**Using your existing Flask instance:**
.. code:: python
from flask import Flask
from slackeventsapi import SlackEventAdapter
# This `app` represents your existing Flask app
app = Flask(__name__)
# An example of one of your Flask app's routes
@app.route("/")
def hello():
return "Hello there!"
# Bind the Events API route to your existing Flask app by passing the server
# instance as the last param, or with `server=app`.
slack_events_adapter = SlackEventAdapter(SLACK_SIGNING_SECRET, "/slack/events", app)
# Create an event listener for "reaction_added" events and print the emoji name
@slack_events_adapter.on("reaction_added")
def reaction_added(event_data):
emoji = event_data["event"]["reaction"]
print(emoji)
# Start the server on port 3000
if __name__ == "__main__":
app.run(port=3000)
For a comprehensive list of available Slack `Events` and more information on
`Scopes`, see https://api.slack.com/events-api
🤖 Example event listeners
-----------------------------
See `example.py`_ for usage examples. This example also utilizes the
SlackClient Web API client.
.. _example.py: /example/
🤔 Support
-----------
Need help? Join `Slack Community`_ and talk to us in `#slack-api`_.
You can also `create an Issue`_ right here on GitHub.
.. _Events API: https://api.slack.com/events-api
.. _create a Slack App: https://api.slack.com/apps/new
.. _Event Subscriptions: https://api.slack.com/events-api#subscriptions
.. _Slack Community: http://slackcommunity.com/
.. _#slack-api: https://dev4slack.slack.com/messages/slack-api/
.. _create an Issue: https://github.com/slackapi/python-slack-events-api/issues/new
Raw data
{
"_id": null,
"home_page": "http://github.com/slackapi/python-slack-events-api",
"name": "slackeventsapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Slack Technologies, LLC",
"author_email": "opensource@slack.com",
"download_url": "https://files.pythonhosted.org/packages/c7/85/1ff2e9a47c5020260f806c82282b5590fbe088e9358d171e601f2fccb3ad/slackeventsapi-3.0.3.tar.gz",
"platform": null,
"description": "Slack Events API adapter for Python\n===================================\n\n.. image:: https://badge.fury.io/py/slackeventsapi.svg\n :target: https://pypi.org/project/slackeventsapi/\n.. image:: https://github.com/slackapi/python-slack-events-api/actions/workflows/ci-build.yml/badge.svg\n :target: https://github.com/slackapi/python-slack-events-api/actions/workflows/ci-build.yml\n.. image:: https://codecov.io/gh/slackapi/python-slack-events-api/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/slackapi/python-slack-events-api\n\n\nThe Slack Events Adapter is a Python-based solution to receive and parse events\nfrom Slack\u2019s Events API. This library uses an event emitter framework to allow\nyou to easily process Slack events by simply attaching functions\nto event listeners.\n\nThis adapter enhances and simplifies Slack's Events API by incorporating useful best practices, patterns, and opportunities to abstract out common tasks.\n\n\ud83d\udca1 We wrote a `blog post which explains how`_ the Events API can help you, why we built these tools, and how you can use them to build production-ready Slack apps.\n\n.. _blog post which explains how: https://medium.com/@SlackAPI/enhancing-slacks-events-api-7535827829ab\n\n\u26a0\ufe0f Important Notice\n---------------------\n\nIf you use this library for Events API handling, you may need to use threads for stable event acknowledgement. See https://github.com/slackapi/python-slack-events-api/issues/84 for details.\n\nIf you're looking for the best recommended library at this point, check Bolt for Python: https://github.com/slackapi/bolt-python\n\nThe framework covers not only Events API but also all the latest Slack Platform features.\n\n\ud83e\udd16 Installation\n----------------\n\n.. code:: shell\n\n pip install slackeventsapi\n\n\ud83e\udd16 App Setup\n--------------------\n\nBefore you can use the `Events API`_ you must\n`create a Slack App`_, and turn on\n`Event Subscriptions`_.\n\n\ud83d\udca1 When you add the Request URL to your app's Event Subscription settings,\nSlack will send a request containing a `challenge` code to verify that your\nserver is alive. This package handles that URL Verification event for you, so\nall you need to do is start the example app, start ngrok and configure your\nURL accordingly.\n\n\u2705 Once you have your `Request URL` verified, your app is ready to start\nreceiving Team Events.\n\n\ud83d\udd11 Your server will begin receiving Events from Slack's Events API as soon as a\nuser has authorized your app.\n\n\ud83e\udd16 Development workflow:\n===========================\n\n(1) Create a Slack app on https://api.slack.com/apps\n(2) Add a `bot user` for your app\n(3) Start the example app on your **Request URL** endpoint\n(4) Start ngrok and copy the **HTTPS** URL\n(5) Add your **Request URL** and subscribe your app to events\n(6) Go to your ngrok URL (e.g. https://myapp12.ngrok.com/) and auth your app\n\n**\ud83c\udf89 Once your app has been authorized, you will begin receiving Slack Events**\n\n \u26a0\ufe0f Ngrok is a great tool for developing Slack apps, but we don't recommend using ngrok\n for production apps.\n\n\ud83e\udd16 Usage\n----------\n **\u26a0\ufe0f Keep your app's credentials safe!**\n\n - For development, keep them in virtualenv variables.\n\n - For production, use a secure data store.\n\n - Never post your app's credentials to github.\n\n.. code:: python\n\n SLACK_SIGNING_SECRET = os.environ[\"SLACK_SIGNING_SECRET\"]\n\nCreate a Slack Event Adapter for receiving actions via the Events API\n-----------------------------------------------------------------------\n**Using the built-in Flask server:**\n\n.. code:: python\n\n from slackeventsapi import SlackEventAdapter\n\n\n slack_events_adapter = SlackEventAdapter(SLACK_SIGNING_SECRET, endpoint=\"/slack/events\")\n\n\n # Create an event listener for \"reaction_added\" events and print the emoji name\n @slack_events_adapter.on(\"reaction_added\")\n def reaction_added(event_data):\n emoji = event_data[\"event\"][\"reaction\"]\n print(emoji)\n\n\n # Start the server on port 3000\n slack_events_adapter.start(port=3000)\n\n\n**Using your existing Flask instance:**\n\n\n.. code:: python\n\n from flask import Flask\n from slackeventsapi import SlackEventAdapter\n\n\n # This `app` represents your existing Flask app\n app = Flask(__name__)\n\n\n # An example of one of your Flask app's routes\n @app.route(\"/\")\n def hello():\n return \"Hello there!\"\n\n\n # Bind the Events API route to your existing Flask app by passing the server\n # instance as the last param, or with `server=app`.\n slack_events_adapter = SlackEventAdapter(SLACK_SIGNING_SECRET, \"/slack/events\", app)\n\n\n # Create an event listener for \"reaction_added\" events and print the emoji name\n @slack_events_adapter.on(\"reaction_added\")\n def reaction_added(event_data):\n emoji = event_data[\"event\"][\"reaction\"]\n print(emoji)\n\n\n # Start the server on port 3000\n if __name__ == \"__main__\":\n app.run(port=3000)\n\nFor a comprehensive list of available Slack `Events` and more information on\n`Scopes`, see https://api.slack.com/events-api\n\n\ud83e\udd16 Example event listeners\n-----------------------------\n\nSee `example.py`_ for usage examples. This example also utilizes the\nSlackClient Web API client.\n\n.. _example.py: /example/\n\n\ud83e\udd14 Support\n-----------\n\nNeed help? Join `Slack Community`_ and talk to us in `#slack-api`_.\n\nYou can also `create an Issue`_ right here on GitHub.\n\n.. _Events API: https://api.slack.com/events-api\n.. _create a Slack App: https://api.slack.com/apps/new\n.. _Event Subscriptions: https://api.slack.com/events-api#subscriptions\n.. _Slack Community: http://slackcommunity.com/\n.. _#slack-api: https://dev4slack.slack.com/messages/slack-api/\n.. _create an Issue: https://github.com/slackapi/python-slack-events-api/issues/new\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Slack Events API adapter for Flask",
"version": "3.0.3",
"project_urls": {
"Homepage": "http://github.com/slackapi/python-slack-events-api"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a24044c2e3d23a44abbe3182f925c5e840d047a4de39fb8ab9f0785aa39dab63",
"md5": "8b2368c0cddda5a329dca3b2c42f4c2a",
"sha256": "4bb62f55d9d5148c6d07ea355d201ff3c8febfd6c8f8e13ff36ae842ec5cc5fa"
},
"downloads": -1,
"filename": "slackeventsapi-3.0.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b2368c0cddda5a329dca3b2c42f4c2a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 7345,
"upload_time": "2024-09-05T01:20:50",
"upload_time_iso_8601": "2024-09-05T01:20:50.701941Z",
"url": "https://files.pythonhosted.org/packages/a2/40/44c2e3d23a44abbe3182f925c5e840d047a4de39fb8ab9f0785aa39dab63/slackeventsapi-3.0.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7851ff2e9a47c5020260f806c82282b5590fbe088e9358d171e601f2fccb3ad",
"md5": "7626a50444b7329604daea7fa8c1785a",
"sha256": "3277b66893bd16f3684b38d860b1fd42af6eca64060c5b7d1f50afbc49eb3b23"
},
"downloads": -1,
"filename": "slackeventsapi-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "7626a50444b7329604daea7fa8c1785a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7340,
"upload_time": "2024-09-05T01:20:52",
"upload_time_iso_8601": "2024-09-05T01:20:52.509665Z",
"url": "https://files.pythonhosted.org/packages/c7/85/1ff2e9a47c5020260f806c82282b5590fbe088e9358d171e601f2fccb3ad/slackeventsapi-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 01:20:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slackapi",
"github_project": "python-slack-events-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "slackeventsapi"
}
JSON
