<h1 align="center">Bolt <img src="https://raw.githubusercontent.com/slackapi/bolt-python/main/docs/static/img/bolt-logo.svg" alt="Bolt logo" width="32"/> for Python</h1>
<p align="center">
<a href="https://pypi.org/project/slack-bolt/">
<img alt="PyPI - Version" src="https://img.shields.io/pypi/v/slack-bolt"></a>
<a href="https://codecov.io/gh/slackapi/bolt-python">
<img alt="Codecov" src="https://img.shields.io/codecov/c/gh/slackapi/bolt-python"></a>
<a href="https://pepy.tech/project/slack-bolt">
<img alt="Pepy Total Downloads" src="https://img.shields.io/pepy/dt/slack-bolt"></a>
<br>
<a href="https://pypi.org/project/slack-bolt/">
<img alt="Python Versions" src="https://img.shields.io/pypi/pyversions/slack-bolt.svg"></a>
<a href="https://tools.slack.dev/bolt-python/">
<img alt="Documentation" src="https://img.shields.io/badge/dev-docs-yellow"></a>
</p>
A Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://tools.slack.dev/bolt-python/getting-started) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt. The Python module documents are available [here](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/).
## Setup
```bash
# Python 3.6+ required
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install slack_bolt
```
## Creating an app
Create a Bolt for Python app by calling a constructor, which is a top-level export. If you'd prefer, you can create an [async app](#creating-an-async-app).
```python
import logging
logging.basicConfig(level=logging.DEBUG)
from slack_bolt import App
# export SLACK_SIGNING_SECRET=***
# export SLACK_BOT_TOKEN=xoxb-***
app = App()
# Add functionality here
if __name__ == "__main__":
app.start(3000) # POST http://localhost:3000/slack/events
```
## Running an app
```bash
export SLACK_SIGNING_SECRET=***
export SLACK_BOT_TOKEN=xoxb-***
python app.py
# in another terminal
ngrok http 3000
```
## Running a Socket Mode app
If you use [Socket Mode](https://api.slack.com/socket-mode) for running your app, `SocketModeHandler` is available for it.
```python
import os
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler
# Install the Slack app and get xoxb- token in advance
app = App(token=os.environ["SLACK_BOT_TOKEN"])
# Add functionality here
if __name__ == "__main__":
# Create an app-level token with connections:write scope
handler = SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"])
handler.start()
```
Run the app this way:
```bash
export SLACK_APP_TOKEN=xapp-***
export SLACK_BOT_TOKEN=xoxb-***
python app.py
# SLACK_SIGNING_SECRET is not required
# Running ngrok is not required
```
## Listening for events
Apps typically react to a collection of incoming events, which can correspond to [Events API events](https://api.slack.com/events-api), [actions](https://api.slack.com/interactivity/components), [shortcuts](https://api.slack.com/interactivity/shortcuts), [slash commands](https://api.slack.com/interactivity/slash-commands) or [options requests](https://api.slack.com/reference/block-kit/block-elements#external_select). For each type of
request, there's a method to build a listener function.
```python
# Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)
app.action(action_id)(fn)
# Listen for dialog submissions
app.action({"callback_id": callbackId})(fn)
# Listen for slash commands
app.command(command_name)(fn)
# Listen for an event from the Events API
app.event(event_type)(fn)
# Listen for a custom step execution from a workflow
app.function(callback_id)(fn)
# Convenience method to listen to only `message` events using a string or re.Pattern
app.message([pattern ,])(fn)
# Listen for options requests (from select menus with an external data source)
app.options(action_id)(fn)
# Listen for a global or message shortcuts
app.shortcut(callback_id)(fn)
# Listen for view_submission modal events
app.view(callback_id)(fn)
```
The recommended way to use these methods are decorators:
```python
@app.event(event_type)
def handle_event(event):
pass
```
## Making things happen
Most of the app's functionality will be inside listener functions (the `fn` parameters above). These functions are called with a set of arguments, each of which can be used in any order. If you'd like to access arguments off of a single object, you can use `args`, an [`slack_bolt.kwargs_injection.Args`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/kwargs_injection/args.py) instance that contains all available arguments for that event.
| Argument | Description |
| :---: | :--- |
| `body` | Dictionary that contains the entire body of the request (superset of `payload`). Some accessory data is only available outside of the payload (such as `trigger_id` and `authorizations`).
| `payload` | Contents of the incoming event. The payload structure depends on the listener. For example, for an Events API event, `payload` will be the [event type structure](https://api.slack.com/events-api#event_type_structure). For a block action, it will be the action from within the `actions` list. The `payload` dictionary is also accessible via the alias corresponding to the listener (`message`, `event`, `action`, `shortcut`, `view`, `command`, or `options`). For example, if you were building a `message()` listener, you could use the `payload` and `message` arguments interchangably. **An easy way to understand what's in a payload is to log it**. |
| `context` | Event context. This dictionary contains data about the event and app, such as the `botId`. Middleware can add additional context before the event is passed to listeners.
| `ack` | Function that **must** be called to acknowledge that your app received the incoming event. `ack` exists for all actions, shortcuts, view submissions, slash command and options requests. `ack` returns a promise that resolves when complete. Read more in [Acknowledging events](https://tools.slack.dev/bolt-python/concepts/acknowledge).
| `respond` | Utility function that responds to incoming events **if** it contains a `response_url` (shortcuts, actions, and slash commands).
| `say` | Utility function to send a message to the channel associated with the incoming event. This argument is only available when the listener is triggered for events that contain a `channel_id` (the most common being `message` events). `say` accepts simple strings (for plain-text messages) and dictionaries (for messages containing blocks).
| `client` | Web API client that uses the token associated with the event. For single-workspace installations, the token is provided to the constructor. For multi-workspace installations, the token is returned by using [the OAuth library](https://tools.slack.dev/bolt-python/concepts/authenticating-oauth), or manually using the `authorize` function.
| `logger` | The built-in [`logging.Logger`](https://docs.python.org/3/library/logging.html) instance you can use in middleware/listeners.
| `complete` | Utility function used to signal the successful completion of a custom step execution. This tells Slack to proceed with the next steps in the workflow. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.
| `fail` | Utility function used to signal that a custom step failed to complete. This tells Slack to stop the workflow execution. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.
## Creating an async app
If you'd prefer to build your app with [asyncio](https://docs.python.org/3/library/asyncio.html), you can import the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library and call the `AsyncApp` constructor. Within async apps, you can use the async/await pattern.
```bash
# Python 3.6+ required
python -m venv .venv
source .venv/bin/activate
pip install -U pip
# aiohttp is required
pip install slack_bolt aiohttp
```
In async apps, all middleware/listeners must be async functions. When calling utility methods (like `ack` and `say`) within these functions, it's required to use the `await` keyword.
```python
# Import the async app instead of the regular one
from slack_bolt.async_app import AsyncApp
app = AsyncApp()
@app.event("app_mention")
async def event_test(body, say, logger):
logger.info(body)
await say("What's up?")
@app.command("/hello-bolt-python")
async def command(ack, body, respond):
await ack()
await respond(f"Hi <@{body['user_id']}>!")
if __name__ == "__main__":
app.start(3000)
```
If you want to use another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at the built-in adapters and their examples.
* [The Bolt app examples](https://github.com/slackapi/bolt-python/tree/main/examples)
* [The built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter)
Apps can be run the same way as the syncronous example above. If you'd prefer another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at [the built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter) and their corresponding [examples](https://github.com/slackapi/bolt-python/tree/main/examples).
## Getting Help
[The documentation](https://tools.slack.dev/bolt-python) has more information on basic and advanced concepts for Bolt for Python. Also, all the Python module documents of this library are available [here](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/).
If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
* [Issue Tracker](http://github.com/slackapi/bolt-python/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for Python. Try searching for an existing issue before creating a new one.
* [Email](mailto:support@slack.com) our developer support team: `support@slack.com`
[pypi-image]: https://badge.fury.io/py/slack-bolt.svg
[pypi-url]: https://pypi.org/project/slack-bolt/
[codecov-image]: https://codecov.io/gh/slackapi/bolt-python/branch/main/graph/badge.svg
[codecov-url]: https://codecov.io/gh/slackapi/bolt-python
[python-version]: https://img.shields.io/pypi/pyversions/slack-bolt.svg
Raw data
{
"_id": null,
"home_page": "https://github.com/slackapi/bolt-python",
"name": "slack-bolt",
"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/b9/9b/afcf997bae7302a907e2667d6073ba2fc0193a4632038f097f5d7289f35c/slack_bolt-1.21.3.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Bolt <img src=\"https://raw.githubusercontent.com/slackapi/bolt-python/main/docs/static/img/bolt-logo.svg\" alt=\"Bolt logo\" width=\"32\"/> for Python</h1>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/slack-bolt/\">\n <img alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/slack-bolt\"></a>\n <a href=\"https://codecov.io/gh/slackapi/bolt-python\">\n <img alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/gh/slackapi/bolt-python\"></a>\n <a href=\"https://pepy.tech/project/slack-bolt\">\n <img alt=\"Pepy Total Downloads\" src=\"https://img.shields.io/pepy/dt/slack-bolt\"></a>\n <br>\n <a href=\"https://pypi.org/project/slack-bolt/\">\n <img alt=\"Python Versions\" src=\"https://img.shields.io/pypi/pyversions/slack-bolt.svg\"></a>\n <a href=\"https://tools.slack.dev/bolt-python/\">\n <img alt=\"Documentation\" src=\"https://img.shields.io/badge/dev-docs-yellow\"></a>\n</p>\n\nA Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://tools.slack.dev/bolt-python/getting-started) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt. The Python module documents are available [here](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/).\n\n## Setup\n\n```bash\n# Python 3.6+ required\npython -m venv .venv\nsource .venv/bin/activate\n\npip install -U pip\npip install slack_bolt\n```\n\n## Creating an app\n\nCreate a Bolt for Python app by calling a constructor, which is a top-level export. If you'd prefer, you can create an [async app](#creating-an-async-app).\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\nfrom slack_bolt import App\n\n# export SLACK_SIGNING_SECRET=***\n# export SLACK_BOT_TOKEN=xoxb-***\napp = App()\n\n# Add functionality here\n\nif __name__ == \"__main__\":\n app.start(3000) # POST http://localhost:3000/slack/events\n```\n\n## Running an app\n\n```bash\nexport SLACK_SIGNING_SECRET=***\nexport SLACK_BOT_TOKEN=xoxb-***\npython app.py\n\n# in another terminal\nngrok http 3000\n```\n\n## Running a Socket Mode app\n\nIf you use [Socket Mode](https://api.slack.com/socket-mode) for running your app, `SocketModeHandler` is available for it.\n\n```python\nimport os\nfrom slack_bolt import App\nfrom slack_bolt.adapter.socket_mode import SocketModeHandler\n\n# Install the Slack app and get xoxb- token in advance\napp = App(token=os.environ[\"SLACK_BOT_TOKEN\"])\n\n# Add functionality here\n\nif __name__ == \"__main__\":\n # Create an app-level token with connections:write scope\n handler = SocketModeHandler(app, os.environ[\"SLACK_APP_TOKEN\"])\n handler.start()\n```\n\nRun the app this way:\n\n```bash\nexport SLACK_APP_TOKEN=xapp-***\nexport SLACK_BOT_TOKEN=xoxb-***\npython app.py\n\n# SLACK_SIGNING_SECRET is not required\n# Running ngrok is not required\n```\n\n## Listening for events\n\nApps typically react to a collection of incoming events, which can correspond to [Events API events](https://api.slack.com/events-api), [actions](https://api.slack.com/interactivity/components), [shortcuts](https://api.slack.com/interactivity/shortcuts), [slash commands](https://api.slack.com/interactivity/slash-commands) or [options requests](https://api.slack.com/reference/block-kit/block-elements#external_select). For each type of\nrequest, there's a method to build a listener function.\n\n```python\n# Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)\napp.action(action_id)(fn)\n\n# Listen for dialog submissions\napp.action({\"callback_id\": callbackId})(fn)\n\n# Listen for slash commands\napp.command(command_name)(fn)\n\n# Listen for an event from the Events API\napp.event(event_type)(fn)\n\n# Listen for a custom step execution from a workflow\napp.function(callback_id)(fn)\n\n# Convenience method to listen to only `message` events using a string or re.Pattern\napp.message([pattern ,])(fn)\n\n# Listen for options requests (from select menus with an external data source)\napp.options(action_id)(fn)\n\n# Listen for a global or message shortcuts\napp.shortcut(callback_id)(fn)\n\n# Listen for view_submission modal events\napp.view(callback_id)(fn)\n```\n\nThe recommended way to use these methods are decorators:\n\n```python\n@app.event(event_type)\ndef handle_event(event):\n pass\n```\n\n## Making things happen\n\nMost of the app's functionality will be inside listener functions (the `fn` parameters above). These functions are called with a set of arguments, each of which can be used in any order. If you'd like to access arguments off of a single object, you can use `args`, an [`slack_bolt.kwargs_injection.Args`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/kwargs_injection/args.py) instance that contains all available arguments for that event.\n\n| Argument | Description |\n| :---: | :--- |\n| `body` | Dictionary that contains the entire body of the request (superset of `payload`). Some accessory data is only available outside of the payload (such as `trigger_id` and `authorizations`).\n| `payload` | Contents of the incoming event. The payload structure depends on the listener. For example, for an Events API event, `payload` will be the [event type structure](https://api.slack.com/events-api#event_type_structure). For a block action, it will be the action from within the `actions` list. The `payload` dictionary is also accessible via the alias corresponding to the listener (`message`, `event`, `action`, `shortcut`, `view`, `command`, or `options`). For example, if you were building a `message()` listener, you could use the `payload` and `message` arguments interchangably. **An easy way to understand what's in a payload is to log it**. |\n| `context` | Event context. This dictionary contains data about the event and app, such as the `botId`. Middleware can add additional context before the event is passed to listeners.\n| `ack` | Function that **must** be called to acknowledge that your app received the incoming event. `ack` exists for all actions, shortcuts, view submissions, slash command and options requests. `ack` returns a promise that resolves when complete. Read more in [Acknowledging events](https://tools.slack.dev/bolt-python/concepts/acknowledge).\n| `respond` | Utility function that responds to incoming events **if** it contains a `response_url` (shortcuts, actions, and slash commands).\n| `say` | Utility function to send a message to the channel associated with the incoming event. This argument is only available when the listener is triggered for events that contain a `channel_id` (the most common being `message` events). `say` accepts simple strings (for plain-text messages) and dictionaries (for messages containing blocks).\n| `client` | Web API client that uses the token associated with the event. For single-workspace installations, the token is provided to the constructor. For multi-workspace installations, the token is returned by using [the OAuth library](https://tools.slack.dev/bolt-python/concepts/authenticating-oauth), or manually using the `authorize` function.\n| `logger` | The built-in [`logging.Logger`](https://docs.python.org/3/library/logging.html) instance you can use in middleware/listeners.\n| `complete` | Utility function used to signal the successful completion of a custom step execution. This tells Slack to proceed with the next steps in the workflow. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.\n| `fail` | Utility function used to signal that a custom step failed to complete. This tells Slack to stop the workflow execution. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.\n\n## Creating an async app\n\nIf you'd prefer to build your app with [asyncio](https://docs.python.org/3/library/asyncio.html), you can import the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library and call the `AsyncApp` constructor. Within async apps, you can use the async/await pattern.\n\n```bash\n# Python 3.6+ required\npython -m venv .venv\nsource .venv/bin/activate\n\npip install -U pip\n# aiohttp is required\npip install slack_bolt aiohttp\n```\n\nIn async apps, all middleware/listeners must be async functions. When calling utility methods (like `ack` and `say`) within these functions, it's required to use the `await` keyword.\n\n```python\n# Import the async app instead of the regular one\nfrom slack_bolt.async_app import AsyncApp\n\napp = AsyncApp()\n\n@app.event(\"app_mention\")\nasync def event_test(body, say, logger):\n logger.info(body)\n await say(\"What's up?\")\n\n@app.command(\"/hello-bolt-python\")\nasync def command(ack, body, respond):\n await ack()\n await respond(f\"Hi <@{body['user_id']}>!\")\n\nif __name__ == \"__main__\":\n app.start(3000)\n```\n\nIf you want to use another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at the built-in adapters and their examples.\n\n* [The Bolt app examples](https://github.com/slackapi/bolt-python/tree/main/examples)\n* [The built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter)\nApps can be run the same way as the syncronous example above. If you'd prefer another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at [the built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter) and their corresponding [examples](https://github.com/slackapi/bolt-python/tree/main/examples).\n\n## Getting Help\n\n[The documentation](https://tools.slack.dev/bolt-python) has more information on basic and advanced concepts for Bolt for Python. Also, all the Python module documents of this library are available [here](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/).\n\nIf you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:\n\n * [Issue Tracker](http://github.com/slackapi/bolt-python/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for Python. Try searching for an existing issue before creating a new one.\n * [Email](mailto:support@slack.com) our developer support team: `support@slack.com`\n\n\n[pypi-image]: https://badge.fury.io/py/slack-bolt.svg\n[pypi-url]: https://pypi.org/project/slack-bolt/\n[codecov-image]: https://codecov.io/gh/slackapi/bolt-python/branch/main/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/slackapi/bolt-python\n[python-version]: https://img.shields.io/pypi/pyversions/slack-bolt.svg\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Bolt Framework for Python",
"version": "1.21.3",
"project_urls": {
"Documentation": "https://slack.dev/bolt-python",
"Homepage": "https://github.com/slackapi/bolt-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3827cf9b0a7c5674ffe841d8c2946f08b7d980738c578a8c99151187925ce27c",
"md5": "ecaac09b66b4cf53b37857f723bc12ef",
"sha256": "f5c41bfd5758db2023a7591e93d05ebb218aaae704e0dc382ae400bc1d5f2670"
},
"downloads": -1,
"filename": "slack_bolt-1.21.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ecaac09b66b4cf53b37857f723bc12ef",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 229651,
"upload_time": "2024-12-05T22:59:49",
"upload_time_iso_8601": "2024-12-05T22:59:49.173579Z",
"url": "https://files.pythonhosted.org/packages/38/27/cf9b0a7c5674ffe841d8c2946f08b7d980738c578a8c99151187925ce27c/slack_bolt-1.21.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b99bafcf997bae7302a907e2667d6073ba2fc0193a4632038f097f5d7289f35c",
"md5": "1616df5fcf0f0138736dfb824a7f6601",
"sha256": "f91ca5dc22da749a42e40a1885b466a4f2af1f65d40c544fccce56e4bb95f1fe"
},
"downloads": -1,
"filename": "slack_bolt-1.21.3.tar.gz",
"has_sig": false,
"md5_digest": "1616df5fcf0f0138736dfb824a7f6601",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 130929,
"upload_time": "2024-12-05T22:59:51",
"upload_time_iso_8601": "2024-12-05T22:59:51.514865Z",
"url": "https://files.pythonhosted.org/packages/b9/9b/afcf997bae7302a907e2667d6073ba2fc0193a4632038f097f5d7289f35c/slack_bolt-1.21.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 22:59:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slackapi",
"github_project": "bolt-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "slack_sdk",
"specs": [
[
">=",
"3.33.5"
],
[
"<",
"4"
]
]
}
],
"lcname": "slack-bolt"
}
JSON
