To listen to messages that your app has access to receive, you can use the message() method which filters out events that aren’t of type message.

message() accepts an argument of type str or re.Pattern object that filters out any messages that don’t match the pattern.

Within your listener function, say() is available whenever there is an associated conversation (for example, a conversation where the event or action which triggered the listener occurred). say() accepts a string to post simple messages and JSON payloads to send more complex messages. The message payload you pass in will be sent to the associated conversation.

In the case that you’d like to send a message outside of a listener or you want to do something more advanced (like handle specific errors), you can call client.chat_postMessage using the client attached to your Bolt instance.

You can listen to any Events API event using the event() method after subscribing to it in your app configuration. This allows your app to take action when something happens in a workspace where it’s installed, like a user reacting to a message or joining a channel.

The event() method requires an eventType of type str.

You can call any Web API method using the WebClient provided to your Bolt app as either app.client or client in middleware/listener arguments (given that your app has the appropriate scopes). When you call one the client’s methods, it returns a SlackResponse which contains the response from Slack.

The token used to initialize Bolt can be found in the context object, which is required to call most Web API methods.

Your app can listen to user actions, like button clicks, and menu selects, using the action method.

Actions can be filtered on an action_id of type str or re.Pattern. action_ids act as unique identifiers for interactive components on the Slack platform.

You’ll notice in all action() examples, ack() is used. It is required to call the ack() function within an action listener to acknowledge that the request was received from Slack. This is discussed in the acknowledging requests section.

There are two main ways to respond to actions. The first (and most common) way is to use say(), which sends a message back to the conversation where the incoming request took place.

The second way to respond to actions is using respond(), which is a utility to use the response_url associated with the action.

Actions, commands, shortcuts, options requests, and view submissions must always be acknowledged using the ack() function. This lets Slack know that the request was received so that it may update the Slack user interface accordingly.

Depending on the type of request, your acknowledgement may be different. For example, when acknowledging a menu selection associated with an external data source, you would call ack() with a list of relevant options. When acknowledging a view submission, you may supply a response_action as part of your acknowledgement to update the view.

We recommend calling ack() right away before initiating any time-consuming processes such as fetching information from your database or sending a new message, since you only have 3 seconds to respond before Slack registers a timeout error.

💡 When working in a FaaS / serverless environment, our guidelines for when to ack() are different. See the section on Lazy listeners (FaaS) for more detail on this.

The shortcut() method supports both global shortcuts and message shortcuts.

Shortcuts are invokable entry points to apps. Global shortcuts are available from within search and text composer area in Slack. Message shortcuts are available in the context menus of messages. Your app can use the shortcut() method to listen to incoming shortcut requests. The method requires a callback_id parameter of type str or re.Pattern.

Shortcuts must be acknowledged with ack() to inform Slack that your app has received the request.

Shortcuts include a trigger_id which an app can use to open a modal that confirms the action the user is taking.

When setting up shortcuts within your app configuration, as with other URLs, you’ll append /slack/events to your request URL.

⚠️ Note that global shortcuts do not include a channel ID. If your app needs access to a channel ID, you may use a conversations_select element within a modal. Message shortcuts do include a channel ID.

Your app can use the command() method to listen to incoming slash command requests. The method requires a command_name of type str.

Commands must be acknowledged with ack() to inform Slack your app has received the request.

There are two ways to respond to slash commands. The first way is to use say(), which accepts a string or JSON payload. The second is respond() which is a utility for the response_url. These are explained in more depth in the responding to actions section.

When setting up commands within your app configuration, you’ll append /slack/events to your request URL.

Modals are focused surfaces that allow you to collect user data and display dynamic information. You can open a modal by passing a valid trigger_id and a view payload to the built-in client’s views.open method.

Your app receives trigger_ids in payloads sent to your Request URL that are triggered by user invocations, like a shortcut, button press, or interaction with a select menu.

Read more about modal composition in the API documentation.

Modals contain a stack of views. When you call views_open, you add the root view to the modal. After the initial call, you can dynamically update a view by calling views_update, or stack a new view on top of the root view by calling views_push.

views_update
To update a view, you can use the built-in client to call views_update with the view_id that was generated when you opened the view, and a new view including the updated blocks list. If you’re updating the view when a user interacts with an element inside of an existing view, the view_id will be available in the body of the request.

views_push
To push a new view onto the view stack, you can use the built-in client to call views_push with a valid trigger_id a new view payload. The arguments for views_push is the same as opening modals. After you open a modal, you may only push two additional views onto the view stack.

Learn more about updating and pushing views in our API documentation.

If a view payload contains any input blocks, you must listen to view_submission requests to receive their values. To listen to view_submission requests, you can use the built-in view() method. view() requires a callback_id of type str or re.Pattern.

You can access the value of the input blocks by accessing the state object. state contains a values object that uses the block_id and unique action_id to store the input values.

Update views on submission

To update a view in response to a view_submission event, you may pass a response_action of type update with a newly composed view to display in your acknowledgement.

1
2
3
4
5
6
7

# Update the view on submission 
@app.view("view_1")
def handle_submission(ack, body):
    # The build_new_view() method returns a modal view
    # To build a modal view, we recommend using Block Kit Builder:
    # https://app.slack.com/block-kit-builder/#%7B%22type%22:%22modal%22,%22callback_id%22:%22view_1%22,%22title%22:%7B%22type%22:%22plain_text%22,%22text%22:%22My%20App%22,%22emoji%22:true%7D,%22blocks%22:%5B%5D%7D
    ack(response_action="update", view=build_new_view(body))

Similarly, there are options for displaying errors in response to view submissions. Read more about view submissions in our API documentation.

Handling views on close

When listening for view_closed requests, you must pass callback_id and add a notify_on_close property to the view during creation. See below for an example of this:

See the API documentation for more information about view_closed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

client.views_open(
    trigger_id=body.get("trigger_id"),
    view={
        "type": "modal",
        "callback_id": "modal-id",  # Used when calling view_closed
        "title": {
            "type": "plain_text",
            "text": "Modal title"
        },
        "blocks": [],
        "close": {
            "type": "plain_text",
            "text": "Cancel"
        },
        "notify_on_close": True,  # This attribute is required
    }
)

# Handle a view_closed request
@app.view_closed("modal-id")
def handle_view_closed(ack, body, logger):
    ack()
    logger.info(body)

Home tabs are customizable surfaces accessible via the sidebar and search that allow apps to display views on a per-user basis. After enabling App Home within your app configuration, home tabs can be published and updated by passing a user_id and view payload to the views.publish method.

You can subscribe to the app_home_opened event to listen for when users open your App Home.

The options() method listens for incoming option request payloads from Slack. Similar to action(), an action_id or constraints object is required. In order to load external data into your select menus, you must provide an options load URL in your app configuration, appended with /slack/events.

While it’s recommended to use action_id for external_select menus, dialogs do not support Block Kit so you’ll have to use the constraints object to filter on a callback_id.

To respond to options requests, you’ll need to call ack() with a valid options or option_groups list. Both external select response examples and dialog response examples can be found on our API site.

Additionally, you may want to apply filtering logic to the returned options based on user input. This can be accomplished by using the payload argument to your options listener and checking for the contents of the value property within it. Based on the value you can return different options. All listeners and middleware handlers in Bolt for Python have access to many useful arguments - be sure to check them out!

Slack apps installed on multiple workspaces will need to implement OAuth, then store installation information (like access tokens) securely. By providing client_id, client_secret, scopes, installation_store, and state_store when initializing App, Bolt for Python will handle the work of setting up OAuth routes and verifying state. If you’re implementing a custom adapter, you can make use of our OAuth library, which is what Bolt for Python uses under the hood.

Bolt for Python will create a Redirect URL slack/oauth_redirect, which Slack uses to redirect users after they complete your app’s installation flow. You will need to add this Redirect URL in your app configuration settings under OAuth and Permissions. This path can be configured in the OAuthSettings argument described below.

Bolt for Python will also create a slack/install route, where you can find an Add to Slack button for your app to perform direct installs of your app. If you need any additional authorizations (user tokens) from users inside a team when your app is already installed or a reason to dynamically generate an install URL, you can pass your own custom URL generator to oauth_settings as authorize_url_generator.

Bolt for Python automatically includes support for org wide installations in version 1.1.0+. Org wide installations can be enabled in your app configuration settings under Org Level Apps.

To learn more about the OAuth installation flow with Slack, read the API documentation.

With the introduction of Socket Mode, Bolt for Python introduced support in version 1.2.0. With Socket Mode, instead of creating a server with endpoints that Slack sends payloads too, the app will instead connect to Slack via a WebSocket connection and receive data from Slack over the socket connection. Make sure to enable Socket Mode in your app configuration settings.

To use the Socket Mode, add SLACK_APP_TOKEN as an environment variable. You can get your App Token in your app configuration settings under the Basic Information section.

While we recommend using the built-in Socket Mode adapter, there are a few other 3rd party library based implementations. Here is the list of available adapters.

Adapters are responsible for handling and parsing incoming requests from Slack to conform to BoltRequest, then dispatching those requests to your Bolt app.

By default, Bolt will use the built-in HTTPServer adapter. While this is okay for local development, it is not recommended for production. Bolt for Python includes a collection of built-in adapters that can be imported and used with your app. The built-in adapters support a variety of popular Python frameworks including Flask, Django, and Starlette among others. Adapters support the use of any production-ready web server of your choice.

To use an adapter, you’ll create an app with the framework of your choosing and import its corresponding adapter. Then you’ll initialize the adapter instance and call its function that handles and parses incoming requests.

The full list adapters, as well as configuration and sample usage, can be found within the repository’s examples folder.

Adapters are flexible and can be adjusted based on the framework you prefer. There are two necessary components of adapters:

• __init__(app: App): Constructor that accepts and stores an instance of the Bolt App.
• handle(req: Request): Function (typically named handle()) that receives incoming Slack requests, parses them to conform to an instance of BoltRequest, then dispatches them to the stored Bolt app.

BoltRequest instantiation accepts four parameters:

Your adapter will return an instance of BoltResponse from the Bolt app.

For more in-depth examples of custom adapters, look at the implementations of the built-in adapters.

To use the async version of Bolt, you can import and initialize an AsyncApp instance (rather than App). AsyncApp relies on AIOHTTP to make API requests, which means you’ll need to install aiohttp (by adding to requirements.txt or running pip install aiohttp).

Sample async projects can be found within the repository’s examples folder.

If an error occurs in a listener, you can handle it directly using a try/except block. Errors associated with your app will be of type BoltError. Errors associated with calling Slack APIs will be of type SlackApiError.

By default, the global error handler will log all non-handled exceptions to the console. To handle global errors yourself, you can attach a global error handler to your app using the app.error(fn) function.

By default, Bolt will log information from your app to the output destination. After you’ve imported the logging module, you can customize the root log level by passing the level parameter to basicConfig(). The available log levels in order of least to most severe are debug, info, warning, error, and critical.

Outside of a global context, you can also log a single message corresponding to a specific level. Because Bolt uses Python’s standard logging module, you can use any its features.

Authorization is the process of determining which Slack credentials should be available while processing an incoming Slack request.

Apps installed on a single workspace can simply pass their bot token into the App constructor using the token parameter. However, if your app will be installed on multiple workspaces, you have two options. The easier option is to use the built-in OAuth support. This will handle setting up OAuth routes and verifying state. Read the section on authenticating with OAuth for details.

For a more custom solution, you can set the authorize parameter to a function upon App instantiation. The authorize function should return an instance of AuthorizeResult, which contains information about who and where the request is coming from.

AuthorizeResult should have a few specific properties, all of type str:

• Either bot_token (xoxb) or user_token (xoxp) are required. Most apps will use bot_token by default. Passing a token allows built-in functions (like say()) to work.
• bot_user_id and bot_id, if using a bot_token.
• enterprise_id and team_id, which can be found in requests sent to your app.
• user_id only when using user_token.

Supported in Bolt for Python as of v1.7.0, token rotation provides an extra layer of security for your access tokens and is defined by the OAuth V2 RFC.

Instead of an access token representing an existing installation of your Slack app indefinitely, with token rotation enabled, access tokens expire. A refresh token acts as a long-lived way to refresh your access tokens.

Bolt for Python supports and will handle token rotation automatically so long as the built-in OAuth functionality is used.

For more information about token rotation, please see the documentation.

Listener middleware is only run for the listener in which it’s passed. You can pass any number of middleware functions to the listener using the middleware parameter, which must be a list that contains one to many middleware functions.

If your listener middleware is a quite simple one, you can use a listener matcher, which returns bool value (True for proceeding) instead of requiring next() method call.

Global middleware is run for all incoming requests, before any listener middleware. You can add any number of global middleware to your app by passing middleware functions to app.use(). Middleware functions are called with the same arguments as listeners, with an additional next() function.

Both global and listener middleware must call next() to pass control of the execution chain to the next middleware.

All listeners have access to a context dictionary, which can be used to enrich requests with additional information. Bolt automatically attaches information that is included in the incoming request, like user_id, team_id, channel_id, and enterprise_id.

context is just a dictionary, so you can directly modify it.

Lazy Listeners are a feature which make it easier to deploy Slack apps to FaaS (Function-as-a-Service) environments. Please note that this feature is only available in Bolt for Python, and we are not planning to add the same to other Bolt frameworks.

Typically when handling actions, commands, shortcuts, options and view submissions, you must acknowledge the request from Slack by calling ack() within 3 seconds. Calling ack() results in sending an HTTP 200 OK response to Slack, letting Slack know that you’re handling the response. We normally encourage you to do this as the very first step in your handler function.

However, when running your app on FaaS or similar runtimes which do not allow you to run threads or processes after returning an HTTP response, we cannot follow the typical pattern of acknowledgement first, processing later. To work with these runtimes, set the process_before_response flag to True. When this flag is true, the Bolt framework holds off sending an HTTP response until all the things in a listener function are done. You need to complete your processing within 3 seconds or you will run into errors with Slack timeouts. Note that in the case of events, while the listener doesn’t need to explicitly call the ack() method, it still needs to complete its function within 3 seconds as well.

To allow you to still run more time-consuming processes as part of your handler, we’ve added a lazy listener function mechanism. Rather than acting as a decorator, a lazy listener accepts two keyword args:

• ack: Callable: Responsible for calling ack() within 3 seconds
• lazy: List[Callable]: Responsible for handling time-consuming processes related to the request. The lazy function does not have access to ack().

Workflow Steps from apps allow your app to create and process custom workflow steps that users can add using Workflow Builder.

A workflow step is made up of three distinct user events:

• Adding or editing the step in a Workflow
• Saving or updating the step’s configuration
• The end user’s execution of the step

All three events must be handled for a workflow step to function.

Read more about workflow steps from apps in the API documentation.

To create a workflow step, Bolt provides the WorkflowStep class.

When instantiating a new WorkflowStep, pass in the step’s callback_id and a configuration object.

The configuration object contains three keys: edit, save, and execute. Each of these keys must be a single callback or a list of callbacks. All callbacks have access to a step object that contains information about the workflow step event.

After instantiating a WorkflowStep, you can pass it into app.step(). Behind the scenes, your app will listen and respond to the workflow step’s events using the callbacks provided in the configuration object.

Alternatively, workflow steps can also be created using the WorkflowStepBuilder class alongside a decorator pattern. For more information, including an example of this approach, refer to the documentation.

When a builder adds (or later edits) your step in their workflow, your app will receive a workflow_step_edit event. The edit callback in your WorkflowStep configuration will be run when this event is received.

Whether a builder is adding or editing a step, you need to send them a workflow step configuration modal. This modal is where step-specific settings are chosen, and it has more restrictions than typical modals—most notably, it cannot include title, submit, or close properties. By default, the configuration modal’s callback_id will be the same as the workflow step.

Within the edit callback, the configure() utility can be used to easily open your step’s configuration modal by passing in the view’s blocks with the corresponding blocks argument. To disable saving the configuration before certain conditions are met, you can also pass in submit_disabled with a value of True.

To learn more about opening configuration modals, read the documentation.

After the configuration modal is opened, your app will listen for the view_submission event. The save callback in your WorkflowStep configuration will be run when this event is received.

Within the save callback, the update() method can be used to save the builder’s step configuration by passing in the following arguments:

• inputs is a dictionary representing the data your app expects to receive from the user upon workflow step execution.
• outputs is a list of objects containing data that your app will provide upon the workflow step’s completion. Outputs can then be used in subsequent steps of the workflow.
• step_name overrides the default Step name
• step_image_url overrides the default Step image

To learn more about how to structure these parameters, read the documentation.

When your workflow step is executed by an end user, your app will receive a workflow_step_execute event. The execute callback in your WorkflowStep configuration will be run when this event is received.

Using the inputs from the save callback, this is where you can make third-party API calls, save information to a database, update the user’s Home tab, or decide the outputs that will be available to subsequent workflow steps by mapping values to the outputs object.

Within the execute callback, your app must either call complete() to indicate that the step’s execution was successful, or fail() to indicate that the step’s execution failed.