0
# Slack Bolt Python Framework
1

2
The Bolt Framework for Python is a comprehensive library for building Slack applications with modern, decorator-based APIs. It provides developers with tools for handling Slack events, actions, shortcuts, slash commands, and interactive components, supporting both synchronous and asynchronous programming models.
3

4
## Package Information
5

6
- **Package Name**: slack-bolt
7
- **Language**: Python
8
- **Installation**: `pip install slack-bolt`
9
- **Repository**: https://github.com/slackapi/bolt-python
10
- **Documentation**: https://slack.dev/bolt-python/
11

12
## Core Imports
13

14
```python
15
from slack_bolt import App
16
```
17

18
For asynchronous applications:
19

20
```python
21
from slack_bolt.async_app import AsyncApp
22
```
23

24
Import additional utilities as needed:
25

26
```python
27
from slack_bolt import BoltContext, Args
28
from slack_bolt.oauth.oauth_flow import OAuthFlow
29
from slack_bolt.oauth.oauth_settings import OAuthSettings
30
from slack_bolt.middleware.custom_middleware import CustomMiddleware
31
```
32

33
## Basic Usage
34

35
### Simple Event Listener App
36

37
```python
38
from slack_bolt import App
39

40
# Initialize app with bot token and signing secret
41
app = App(
42
    token="xoxb-your-bot-token",
43
    signing_secret="your-signing-secret"
44
)
45

46
# Listen for message events containing "hello"
47
@app.message("hello")
48
def say_hello(message, say):
49
    say(f"Hello <@{message['user']}>!")
50

51
# Listen for slash commands
52
@app.command("/weather")
53
def weather_command(ack, respond, command):
54
    ack()  # Always acknowledge commands immediately
55
    city = command['text'] or "San Francisco"
56
    respond(f"The weather in {city} is sunny! ☀️")
57

58
# Listen for button clicks
59
@app.action("approve_button")
60
def handle_approve(ack, respond, body):
61
    ack()
62
    user = body["user"]["name"]
63
    respond(f"<@{user}> approved the request!")
64

65
# Start the app
66
if __name__ == "__main__":
67
    app.start(port=int(os.environ.get("PORT", 3000)))
68
```
69

70
### Multi-Workspace OAuth App
71

72
```python
73
from slack_bolt import App
74
from slack_bolt.oauth.oauth_flow import OAuthFlow
75
from slack_bolt.oauth.oauth_settings import OAuthSettings
76

77
# Configure OAuth flow for multi-workspace installation
78
oauth_settings = OAuthSettings(
79
    client_id="your-client-id",
80
    client_secret="your-client-secret",
81
    scopes=["chat:write", "commands", "app_mentions:read"],
82
    install_path="/slack/install",
83
    redirect_uri_path="/slack/oauth_redirect"
84
)
85

86
app = App(
87
    signing_secret="your-signing-secret",
88
    oauth_settings=oauth_settings
89
)
90

91
@app.event("app_mention")
92
def handle_mention(event, say):
93
    say(f"Thanks for mentioning me, <@{event['user']}>!")
94

95
app.start(port=3000)
96
```
97

98
## Architecture
99

100
Slack Bolt follows an event-driven architecture with several key components:
101

102
- **App/AsyncApp**: Main application class that manages listeners, middleware, and request routing
103
- **Listeners**: Decorator-based functions that respond to specific Slack events, commands, or actions
104
- **Context Objects**: Rich objects providing utilities like `ack()`, `say()`, `respond()`, and `client` for API calls
105
- **Middleware**: Request processing pipeline for authentication, logging, and custom logic
106
- **Adapters**: Integration layers for web frameworks like FastAPI, Flask, Django, and cloud platforms
107

108
The framework supports both single-workspace apps (with hardcoded tokens) and multi-workspace apps (with OAuth installation flows), and provides both synchronous and asynchronous programming models.
109

110
## Capabilities
111

112
### App Configuration & Setup
113

114
Core application setup including single vs multi-workspace configuration, OAuth flows, Socket Mode, and essential middleware options. Covers both App and AsyncApp initialization patterns.
115

116
```python { .api }
117
class App:
118
    def __init__(
119
        self,
120
        *,
121
        logger=None,
122
        name: str = None,
123
        process_before_response: bool = False,
124
        signing_secret: str = None,
125
        token: str = None,
126
        client=None,
127
        authorize=None,
128
        installation_store=None,
129
        oauth_settings: OAuthSettings = None,
130
        oauth_flow: OAuthFlow = None,
131
        # ... many more configuration options
132
    ): ...
133
    
134
    def start(self, port: int = 3000, path: str = "/slack/events", host: str = "0.0.0.0"): ...
135
```
136

137
[App Configuration & Setup](./app-configuration.md)
138

139
### Event Listeners & Request Handling
140

141
Decorator-based event handling for all Slack event types including messages, slash commands, interactive components, shortcuts, and view submissions. Supports event filtering and custom matchers.
142

143
```python { .api }
144
def message(self, keyword=None, *matchers): ...
145
def command(self, command, *matchers): ...
146
def event(self, event_type, *matchers): ...
147
def action(self, action_id, *matchers): ...
148
def shortcut(self, callback_id, *matchers): ...
149
def view(self, callback_id, *matchers): ...
150
def options(self, action_id, *matchers): ...
151
```
152

153
[Event Listeners & Request Handling](./event-listeners.md)
154

155
### Context Objects & Utilities
156

157
Rich context objects providing utilities for acknowledging requests, sending messages, making API calls, and accessing request data. Includes argument injection system for clean listener functions.
158

159
```python { .api }
160
class BoltContext:
161
    client: WebClient
162
    ack: Ack
163
    say: Say
164
    respond: Respond
165
    logger: Logger
166
    # ... additional properties
167
    
168
def ack(response=None): ...
169
def say(text: str = None, **kwargs): ...
170
def respond(text: str = None, **kwargs): ...
171
```
172

173
[Context Objects & Utilities](./context-and-utilities.md)
174

175
### OAuth & Multi-Workspace Installation
176

177
OAuth 2.0 flow implementation for multi-workspace Slack app installation and management. Includes installation stores, token management, and authorization patterns.
178

179
```python { .api }
180
class OAuthFlow:
181
    def __init__(self, *, settings: OAuthSettings, logger: Logger = None): ...
182

183
class OAuthSettings:
184
    def __init__(
185
        self,
186
        *,
187
        client_id: str,
188
        client_secret: str,
189
        scopes: Union[str, Sequence[str]],
190
        redirect_uri_path: str = "/slack/oauth_redirect",
191
        install_path: str = "/slack/install"
192
    ): ...
193
```
194

195
[OAuth & Multi-Workspace Installation](./oauth-and-installation.md)
196

197
### Middleware System
198

199
Request processing pipeline with built-in middleware for authentication, request verification, and logging. Supports custom middleware development and per-listener middleware.
200

201
```python { .api }
202
def use(self, *middleware): ...
203
def middleware(self, *middleware): ...
204
def error(self, error_handler): ...
205

206
class CustomMiddleware:
207
    def __init__(self, app_name: str = None): ...
208
    def process(self, *, req: BoltRequest, resp: BoltResponse, next): ...
209
```
210

211
[App Configuration & Setup](./app-configuration.md)
212

213
### Interactive UI Components
214

215
Handling of Slack's interactive UI components including Block Kit elements, modal views, shortcuts, and form submissions. Covers view management and complex UI workflows.
216

217
```python { .api }
218
def view_submission(self, callback_id, *matchers): ...
219
def view_closed(self, callback_id, *matchers): ...
220
def block_action(self, action_id, *matchers): ...
221
def global_shortcut(self, callback_id, *matchers): ...
222
def message_shortcut(self, callback_id, *matchers): ...
223
```
224

225
[Event Listeners & Request Handling](./event-listeners.md)
226

227
### Web Framework Integration
228

229
Adapters for integrating Bolt apps with popular Python web frameworks and deployment platforms. Supports FastAPI, Flask, Django, ASGI/WSGI, and cloud platforms.
230

231
```python { .api }
232
# FastAPI example
233
from slack_bolt.adapter.fastapi import SlackRequestHandler
234
handler = SlackRequestHandler(app)
235
fastapi_app.post("/slack/events")(handler.handle)
236

237
# Flask example  
238
from slack_bolt.adapter.flask import SlackRequestHandler
239
handler = SlackRequestHandler(app)
240
flask_app.route("/slack/events", methods=["POST"])(handler.handle)
241
```
242

243
[Web Framework Integration](./framework-integration.md)
244

245
### AI Agents & Assistant Features
246

247
AI assistant middleware for building conversational AI experiences within Slack. Includes thread context management, assistant-specific utilities, and workflow integration.
248

249
```python { .api }
250
from slack_bolt.middleware.assistant import Assistant
251

252
class Assistant:
253
    def __init__(self, thread_context_store=None): ...
254

255
def set_status(text: str): ...
256
def set_title(title: str): ...
257
def set_suggested_prompts(prompts: List[str]): ...
258
def save_thread_context(context: dict): ...
259
```
260

261
[Context Objects & Utilities](./context-and-utilities.md)
262

263
### Asynchronous Programming
264

265
AsyncApp for high-performance asynchronous Slack applications. Includes async decorators, utilities, and integration patterns for async web frameworks.
266

267
```python { .api }
268
class AsyncApp:
269
    def __init__(self, **kwargs): ...
270
    
271
    async def start_async(self, port: int = 3000): ...
272
    
273
    def message(self, keyword=None, *matchers): ...  # Returns async decorator
274
    def command(self, command, *matchers): ...       # Returns async decorator
275
```
276

277
[App Configuration & Setup](./app-configuration.md)
278

279
## Error Handling
280

281
```python { .api }
282
class BoltError(Exception): ...
283

284
class BoltUnhandledRequestError(BoltError):
285
    request: BoltRequest
286
    body: dict
287
    current_response: BoltResponse
288
    last_global_middleware_name: str
289
```
290

291
Common error patterns and debugging techniques are covered in the middleware and context documentation.
292

293
## Version Information
294

295
```python { .api }
296
__version__ = "1.24.0"
297
```