You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Python framework to build Slack apps in a flash with the latest platform features. Check the [document](https://slack.dev/bolt-python/) and [examples](https://github.com/slackapi/bolt-python/tree/main/examples) to know how to use this framework.
8
+
A Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://slack.dev/bolt-python/tutorial/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.
9
9
10
10
## Setup
11
11
@@ -18,9 +18,9 @@ pip install -U pip
18
18
pip install slack_bolt
19
19
```
20
20
21
-
## First Bolt App (app.py)
21
+
## Creating an app
22
22
23
-
Create an app by calling a constructor, which is a top-level export.
23
+
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).
# acknowledge the incoming request from Slack immediately
45
-
ack()
46
-
# open a modal
47
-
api_response = client.views_open(
48
-
trigger_id=body["trigger_id"],
49
-
view={
50
-
"type": "modal",
51
-
"callback_id": "view-id",
52
-
"title": {
53
-
"type": "plain_text",
54
-
"text": "My App",
55
-
},
56
-
"submit": {
57
-
"type": "plain_text",
58
-
"text": "Submit",
59
-
},
60
-
"blocks": [
61
-
{
62
-
"type": "input",
63
-
"block_id": "b",
64
-
"element": {
65
-
"type": "plain_text_input",
66
-
"action_id": "a"
67
-
},
68
-
"label": {
69
-
"type": "plain_text",
70
-
"text": "Label",
71
-
}
72
-
}
73
-
]
74
-
})
75
-
logger.debug(api_response)
76
-
77
-
@app.view("view-id")
78
-
defview_submission(ack, view, logger):
79
-
ack()
80
-
# Prints {'b': {'a': {'type': 'plain_text_input', 'value': 'Your Input'}}}
81
-
logger.info(view["state"]["values"])
35
+
# Add functionality here
82
36
83
37
if__name__=="__main__":
84
38
app.start(3000) # POST http://localhost:3000/slack/events
85
39
```
86
40
87
-
## Run the Bolt App
41
+
## Running an app
88
42
89
43
```bash
90
44
export SLACK_SIGNING_SECRET=***
@@ -95,9 +49,61 @@ python app.py
95
49
ngrok http 3000
96
50
```
97
51
98
-
## AsyncApp Setup
52
+
## Listening for events
53
+
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
54
+
request, there's a method to build a listener function.
55
+
56
+
```python
57
+
# Listen for an event from the Events API
58
+
app.event(event_type, fn)
59
+
60
+
# Convenience method to listen to only `message` events using a string or re.Pattern
61
+
app.message([pattern ,] fn)
62
+
63
+
# Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)
64
+
app.action(action_id, fn)
65
+
66
+
# Listen for dialog submissions
67
+
app.action({"callback_id": callbackId}, fn)
68
+
69
+
# Listen for a global or message shortcuts
70
+
app.shortcut(callback_id, fn)
71
+
72
+
# Listen for slash commands
73
+
app.command(command_name, fn)
74
+
75
+
# Listen for view_submission modal events
76
+
app.view(callback_id, fn)
77
+
78
+
# Listen for options requests (from select menus with an external data source)
79
+
app.options(action_id, fn)
80
+
```
81
+
82
+
The recommended way to use these methods are decorators:
83
+
84
+
```python
85
+
@app.event(event_type)
86
+
defhandle_event(event):
87
+
pass
88
+
```
89
+
90
+
## Making things happen
91
+
92
+
Most of the app's functionality will be inside listener functions (the `fn` parameters above). These functions are called with a set of arguments.
93
+
94
+
| Argument | Description |
95
+
| :---: | :--- |
96
+
|`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**. |
97
+
| `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).
98
+
| `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://slack.dev/bolt-python/concepts#acknowledge).
99
+
| `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://slack.dev/bolt-python/concepts#authenticating-oauth), or manually using the `authorize` function.
100
+
| `respond` | Utility function that responds to incoming events **if** it contains a `response_url` (shortcuts, actions, and slash commands).
101
+
| `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.
102
+
| `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 `authed_users`).
103
+
104
+
## Creating an async app
99
105
100
-
If you prefer building Slack apps using [asyncio](https://docs.python.org/3/library/asyncio.html), you can go with `AsyncApp` instead. You can use async/await style for everything in the app. To use `AsyncApp`, [AIOHTTP](https://docs.aiohttp.org/en/stable/) library is required for asynchronous Slack Web API calls and the default web server.
106
+
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.
101
107
102
108
```bash
103
109
# Python 3.6+ required
@@ -109,9 +115,10 @@ pip install -U pip
109
115
pip install slack_bolt aiohttp
110
116
```
111
117
112
-
Import `slack_bolt.async_app.AsyncApp` instead of `slack_bolt.App`. All middleware/listeners must be async functions. Inside the functions, all utility methods such as `ack`, `say`, and `respond` requires`await` keyword.
118
+
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.
113
119
114
120
```python
121
+
# Import the async app instead of the regular one
115
122
from slack_bolt.async_app import AsyncApp
116
123
117
124
app = AsyncApp()
@@ -130,29 +137,21 @@ if __name__ == "__main__":
130
137
app.start(3000)
131
138
```
132
139
133
-
Starting the app is exactly the same with the way using `slack_bolt.App`.
134
-
135
-
```bash
136
-
export SLACK_SIGNING_SECRET=***
137
-
export SLACK_BOT_TOKEN=xoxb-***
138
-
python app.py
139
-
140
-
# in another terminal
141
-
ngrok http 3000
142
-
```
143
-
144
140
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.
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 [sample code](https://github.com/slackapi/bolt-python/tree/main/samples).
145
+
146
+
## Getting Help
148
147
149
-
# Feedback
148
+
[The documentation](https://slack.dev/bolt-python) has more information on basic and advanced concepts for Bolt for Python.
150
149
151
-
We are keen to hear your feedback. Please feel free to [submit an issue](https://github.com/slackapi/bolt-python/issues)!
150
+
If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
152
151
153
-
# License
152
+
*[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.
0 commit comments