Commit ec26011

This quickstart guide aims to help you get a Slack app using Bolt for Python up and running as soon as possible!

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-python-getting-started-app) running to modify and make your own.

:::tip[Reference for readers]

In search of the complete guide to building an app from scratch? Check out the [building an app](/tools/bolt-python/building-an-app) guide.

A few tools are needed for the following steps. We recommend using the [**Slack CLI**](/tools/slack-cli/) for the smoothest experience, but other options remain available.

You can also begin by installing git and downloading [Python 3.7 or later](https://www.python.org/downloads/), or the latest stable version of Python. Refer to [Python's setup and building guide](https://devguide.python.org/getting-started/setup-building/) for more details.

Install the latest version of the Slack CLI to get started:

- [Slack CLI for macOS & Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux)

- [Slack CLI for Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows)

Then confirm a successful installation with the following command:

$ slack version

An authenticated login is also required if this hasn't been done before:

$ slack login

:::info[A place to belong]

A workspace where development can happen is also needed.

With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app.

If you don’t already have a project, let’s create a new one!

<Tabs groupId="cli-or-terminal">

<TabItem value="cli" label="Slack CLI">

A starter template can be used to start with project scaffolding:

$ slack create first-bolt-app --template slack-samples/bolt-python-getting-started-app

$ cd first-bolt-app

After a project is created you'll have a `requirements.txt` file for app dependencies and a `.slack` directory for Slack CLI configuration.

A few other files exist too, but we'll visit these later.

</TabItem>

<TabItem value="terminal" label="Terminal">

A starter template can be cloned to start with project scaffolding:

$ git clone https://github.com/slack-samples/bolt-python-getting-started-app first-bolt-app

$ cd first-bolt-app

Outlines of a project are taking shape, so we can move on to running the app!

</TabItem>

</Tabs>

We recommend using a [Python virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to manage your project's dependencies. This is a great way to prevent conflicts with your system's Python packages. Let's create and activate a new virtual environment with [Python 3.7 or later](https://www.python.org/downloads/):

$ python3 -m venv .venv

$ source .venv/bin/activate

$ pip install -r requirements.txt

Confirm the virtual environment is active by checking that the path to `python3` is _inside_ your project ([a similar command is available on Windows](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment)):

$ which python3

Before you can start developing with Bolt, you will want a running Slack app.

<Tabs groupId="cli-or-terminal">

<TabItem value="cli" label="Slack CLI">

The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice:

$ slack run

...

⚡️ Bolt app is running!

With the app running, you can test it out with the following steps in Slack:

1. Open a direct message with your app or invite the bot `@first-bolt-app (local)` to a public channel.

2. Send "hello" to the current conversation and wait for a response.

3. Click the attached button labelled "Click Me" to post another reply.

After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running.

</TabItem>

<TabItem value="terminal" label="Browser">

Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option:

1. Select the workspace to develop your app in.

2. Copy and paste the `manifest.json` file contents to create your app.

3. Confirm the app features and click "Create".

You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials:


To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](/tools/bolt-python/concepts/socket-mode). This connection requires a specific app token:

1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**.

2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**.

3. Save the generated `xapp` token as an environment variable within your project:

$ export SLACK_APP_TOKEN=<your-app-level-token>

The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153).

:::warning[Keep it secret. Keep it safe.]

Treat your tokens like a password and [keep it safe](/security). Your app uses these to retrieve and send information to Slack.

A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows:

1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token.

2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**:


3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable:

$ export SLACK_BOT_TOKEN=xoxb-<your-bot-token>

After saving tokens for the app you created, it is time to run it:

$ python3 app.py

...

⚡️ Bolt app is running!

1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel.

3. Click the attached button labelled "Click Me" to post another reply.

</TabItem>

</Tabs>

<Tabs groupId="cli-or-terminal">

<TabItem value="cli" label="Slack CLI">

</TabItem>

<TabItem value="terminal" label="Terminal">

Run the following command to start, or restart, your app with the latest changes:

$ python3 app.py

...

⚡️ Bolt app is running!

After finding the above output appears, open Slack to perform these steps:

1. Return to the direct message or public channel with your bot.

2. Send "goodbye" to the conversation.

3. Receive a parting response from before and repeat "goodbye" to find another one.

Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats.

</TabItem>

</Tabs>

<Tabs groupId="cli-or-terminal">

<TabItem value="cli" label="Slack CLI">

</TabItem>

<TabItem value="terminal" label="Browser">

Browse to https://api.slack.com/apps and select your app "Getting Started Bolt App" from the list.

This will open the following page:


</TabItem>

</Tabs>

- Follow along with the steps that went into making this app on the [creating an app](/tools/bolt-python/creating-an-app) guide for an educational overview.