title: Authenticating with OAuth

lang: en

slug: authenticating-oauth

order: 14

<div class="section-content">

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 receiver, you can make use of our [OAuth library](https://slack.dev/python-slack-sdk/oauth), 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`.

To learn more about the OAuth installation flow with Slack, [read the API documentation](https://api.slack.com/authentication/oauth-v2).

</div>

oauth_settings = OAuthSettings(

client_id=os.environ["SLACK_CLIENT_ID"],

client_secret=os.environ["SLACK_CLIENT_SECRET"],

scopes=["channels:read", "groups:read", "chat:write"],

installation_store=FileInstallationStore(),

state_store=FileOAuthStateStore(expiration_seconds=120)

)

app = App(signing_secret=os.environ["SIGNING_SECRET"],

oauth_settings=oauth_settings)

<details class="secondary-wrapper">

<summary class="section-head" markdown="0">

<h4 class="section-head">Customizing OAuth defaults</h4>

</summary>

<div class="secondary-content" markdown="0">

You can override the default OAuth using `oauth_settings`, which can be passed in during the initialization of App. You can override the following:

- `authorization_url`: Used to toggle between new Slack Apps and Classic Slack Apps

- `install_path`: Override default path for "Add to Slack" button

- `redirect_uri`: Override default redirect url path

- `callback_options`: Provide custom success and failure pages at the end of the OAuth flow

- `state_store`: Provide a custom state store instead of using the built in `OAuthStateStore`

</div>

oauth_settings = OAuthSettings(

client_id=os.environ["SLACK_CLIENT_ID"],

client_secret=os.environ["SLACK_CLIENT_SECRET"],

scopes=["channels:read", "groups:read", "chat:write", "incoming-webhook"],

installation_store=FileInstallationStore(),

state_store=FileOAuthStateStore(expiration_seconds=120),

install_path="/slack/install_app",

redirect_uri_path="/slack/redirect",

callback_options=CallbackOptions(success=success_handler,

failure=failure_handler)

)

app = App(signing_secret=os.environ["SIGNING_SECRET"],

oauth_settings=oauth_settings)

</details>

title: Listening to actions

lang: en

slug: action-listening

order: 5

<div class="section-content">

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 `RegExp` object. `action_id`s 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 event was received from Slack. This is discussed in the [acknowledging events section](#acknowledge).

</div>

@app.action("approve_button")

def update_message(ack):

ack()

# Update the message to reflect the action

<details class="secondary-wrapper">

<summary class="section-head" markdown="0">

<h4 class="section-head">Listening to actions using a constraint object</h4>

</summary>

<div class="secondary-content" markdown="0">

You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type `str` or `RegExp` object.

</div>

@app.action({"action_id": "select_user", "block_id": "assign_ticket"})

def update_message(ack, action, client):

ack()

client.reactions_add(name='white_check_mark',

timestamp=action['ts'],

channel=action['channel'])

</details>

title: Listening to events

lang: en

slug: event-listening

order: 3

<div class="section-content">

You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method after subscribing to it in your app configuration. This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.

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

</div>

@app.event("team_join")

def ask_for_introduction(payload, say):

welcome_channel_id = "C12345";

user_id = payload["event"]["user"]

text = f"Welcome to the team, <@{user_id}>! 🎉 You can introduce yourself in this channel."

say(text=text, channel=welcome_channel_id)

<details class="secondary-wrapper" >

<summary class="section-head" markdown="0">

<h4 class="section-head">Filtering on message subtypes</h4>

</summary>

<div class="secondary-content" markdown="0">

The `message()` listener is equivalent to `event("message")`.

You can filter on subtypes of events by passing in the additional key `subtype`. Common message subtypes like `bot_message` and `message_replied` can be found [on the message event page](https://api.slack.com/events/message#message_subtypes).

</div>

@app.message({"subtype": "message_changed"})

def log_message_change(logger, payload):

message = payload["event"]

logger.info(f"The user {message['user']} changed the message to {message['text']}")

</details>

title: Listening to messages

lang: en

slug: message-listening

order: 1

<div class="section-content">

To listen to messages that [your app has access to receive](https://api.slack.com/messaging/retrieving#permissions), you can use the `message()` method which filters out events that aren’t of type `message`.

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

</div>

@app.message(":wave:")

def say_hello(payload, say):

user = payload['event']['user']

say(f"Hi there, <@{user}>!")

<details class="secondary-wrapper">

<summary markdown="0">

<h4 class="secondary-header">Using a RegEx pattern</h4>

</summary>

<div class="secondary-content" markdown="0">

The `re.compile()` method can be used instead of a string for more granular matching.

</div>

@app.message(re.compile("(hi|hello|hey)"))

def say_hello_regex(say, context):

# RegExp matches are inside of context.matches

greeting = context['matches'][0]

say(f"{greeting}, how are you?")

</details>

title: Listening for view submissions

lang: en

slug: view_submissions

order: 12

<div class="section-content">

If a <a href="https://api.slack.com/reference/block-kit/views">view payload</a> contains any input blocks, you must listen to `view_submission` events to receive their values. To listen to `view_submission` events, you can use the built-in `view()` method. `view()` requires a `callback_id` of type `str` or `RegExp`.

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.

Read more about view submissions in our <a href="https://api.slack.com/surfaces/modals/using#interactions">API documentation</a>.

</div>

@app.view("view_b")

def handle_submission(ack, body, client, view):

# Acknowledge the view_submission event

ack()

# Do whatever you want with the input data - here we're saving it to a DB then sending the user a verifcation of their submission

# Assume there's an input block with `block_1` as the block_id and `input_a`

val = view["state"]["values"]["block_1"]["input_a"]

user = body["user"]["id"]

# Message to send user

msg = ""

# TODO: Store in DB

if results:

msg = "Your submission was successful"

else:

msg = "There was an error with your submission"

# Message the user

client.chat_postMessage(channel=user, text=msg)

title: Listening and responding to commands

lang: en

slug: commands

order: 9

<div class="section-content">

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

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

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](#action-respond) section.

When configuring commands within your app configuration, you'll continue to append `/slack/events` to your request URL.

</div>

@app.command("/echo")

def repeat_text(ack, say, command):

# Acknowledge command request

ack()

say(f"{command['text']}")

title: Listening and responding to options

lang: en

slug: options

order: 13

<div class="section-content">

The `options()` method listens for incoming option request payloads from Slack. [Similar to `action()`](#action-listening),

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.

While it's recommended to use `action_id` for `external_select` menus, dialogs do not yet 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 `ack()` with valid options. Both [external select response examples](https://api.slack.com/reference/messaging/block-elements#external-select) and [dialog response examples](https://api.slack.com/dialogs#dynamic_select_elements_external) can be found on our API site.

</div>

@app.options("external_action")

def show_options(ack):

options = [

{

"text": {"type": "plain_text", "text": "Option 1"},

"value": "1-1",

},

{

"text": {"type": "plain_text", "text": "Option 2"},

"value": "1-2",

},

]

ack({"options": options})