diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..dde7088a3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "workbench.colorTheme": "Abyss" +} \ No newline at end of file diff --git a/docs/english/getting-started.md b/docs/english/getting-started.md index 6964df23b..584fce088 100644 --- a/docs/english/getting-started.md +++ b/docs/english/getting-started.md @@ -3,193 +3,87 @@ sidebar_label: Quickstart title: Quickstart guide with Bolt for Python --- -This quickstart guide aims to help you get a Slack app using Bolt for Python up and running as soon as possible! +This quickstart guide will get you a running Slack app using Bolt for Python. When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-python-getting-started-app) that responds to "hello" messages. You'll then be able to modify it and make it your own. -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. +## Setting up the app -:::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. - -::: - -#### Prerequisites - -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: - -```sh -$ slack version -``` - -An authenticated login is also required if this hasn't been done before: - -```sh -$ slack login -``` - -:::info[A place to belong] - -A workspace where development can happen is also needed. +:::info[A workspace where development can happen is needed.] We recommend using [developer sandboxes](/tools/developer-sandboxes) to avoid disruptions where real work gets done. ::: -## Creating a project {#creating-a-project} - -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! - - - - -A starter template can be used to start with project scaffolding: - -```sh -$ 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. - - - - -A starter template can be cloned to start with project scaffolding: +import QuickstartGuide from '@site/src/components/QuickstartGuide'; + + -```sh -$ 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! - - - - -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/): - -```sh -$ 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)): - -```sh -$ which python3 -# Output: /path/to/first-bolt-app/.venv/bin/python3 -``` +--- ## Running the app {#running-the-app} -Before you can start developing with Bolt, you will want a running Slack app. +Now that you're inside the directory, let's get the app running: - - - -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: - -```sh +```zsh $ 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. - - - - -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: - -![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page") - -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: - -```sh -$ export SLACK_APP_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). +You can test it out with the following steps in Slack: -:::warning[Keep it secret. Keep it safe.] +1. Invite the bot `@first-bolt-app (local)` to a public channel. You can do this a few ways: -Treat your tokens like a password and [keep it safe](/security). Your app uses these to retrieve and send information to Slack. + Option A: @-mention them in a message in a channel. You will be prompted to add them. -::: - -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**: - -![OAuth Tokens](/img/bolt-python/bot-token.png "Bot OAuth Token") - -3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable: - -```sh -$ export SLACK_BOT_TOKEN=xoxb- -``` - -After saving tokens for the app you created, it is time to run it: - -```sh -$ python3 app.py -... -⚡️ 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 `@BoltApp` to a public channel. + Option B: Click the channel name, go to the "Integrations" tab, and click the "Add apps" button. + 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. - - +--- -## Updating the app +## Extra credit: updating the app -At this point, you've successfully run the getting started Bolt for Python [app](https://github.com/slack-samples/bolt-python-getting-started-app)! +At this point, you've successfully run the Bolt for Python [getting started app](https://github.com/slack-samples/bolt-python-getting-started-app)! The defaults included leave opportunities abound, so to personalize this app let's now edit the code to respond with a kind farewell. -#### Responding to a farewell +### Responding to a farewell Chat is a common thing apps do and responding to various types of messages can make conversations more interesting. @@ -205,20 +99,7 @@ def message_goodbye(say): say(f"{parting}!") ``` -Once the file is updated, save the changes and then we'll make sure those changes are being used. - - - - -Run the following command and select the app created earlier to start, or restart, your app with the latest changes: - -```sh -$ slack run -... -⚡️ Bolt app is running! -``` - -After finding the above output appears, open Slack to perform these steps: +Once the file is updated, save the changes. The Slack CLI will restart the app for you. Then open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. @@ -226,63 +107,10 @@ After finding the above output appears, open Slack to perform these steps: Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. - - - -Run the following command to start, or restart, your app with the latest changes: - -```sh -$ 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. - - - - -#### Customizing app settings - -The created app will have some placeholder values and a small set of [scopes](/reference/scopes) to start, but we recommend exploring the customizations possible on app settings. - - - - -Open app settings for your app with the following command: - -```sh -$ slack app settings -``` - -This will open the following page in a web browser: - -![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page") - - - - -Browse to https://api.slack.com/apps and select your app "Getting Started Bolt App" from the list. - -This will open the following page: - -![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page") - - - - -On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app! - ## Next steps {#next-steps} You can now continue customizing your app with various features to make it right for whatever job's at hand. Here are some ideas about what to explore next: -- 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. +- Learn the steps that went into making this app on the [creating an app](/tools/bolt-python/creating-an-app) guide for an educational overview. This is also where you can learn how to create the app without using the Slack CLI. - Check out the [Agent quickstart](/ai/agent-quickstart) to get up and running with an agent. - Browse our [curated catalog of samples](/samples) for more apps to use as a starting point for development. \ No newline at end of file diff --git a/docs/english/tutorial/ai-chatbot/ai-chatbot.md b/docs/english/tutorial/ai-chatbot/ai-chatbot.md index 2fcc16e9a..933ea6db5 100644 --- a/docs/english/tutorial/ai-chatbot/ai-chatbot.md +++ b/docs/english/tutorial/ai-chatbot/ai-chatbot.md @@ -68,10 +68,10 @@ Models from different AI providers are available if the corresponding environmen -To interact with Anthropic models, navigate to your Anthropic account dashboard to [create an API key](https://console.anthropic.com/settings/keys), then export the key as follows: +To interact with Anthropic models, navigate to your Anthropic account dashboard to [create an API key](https://console.anthropic.com/settings/keys), then set it using the Slack CLI: ```bash -export ANTHROPIC_API_KEY= +slack env set ANTHROPIC_API_KEY ``` @@ -79,11 +79,11 @@ export ANTHROPIC_API_KEY= To use Google Cloud Vertex AI, [follow this quick start](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#expandable-1) to create a project for sending requests to the Gemini API, then gather [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) with the strategy to match your development environment. -Once your project and credentials are configured, export environment variables to select from Gemini models: +Once your project and credentials are configured, set environment variables using the Slack CLI to select from Gemini models: ```bash -export VERTEX_AI_PROJECT_ID= -export VERTEX_AI_LOCATION= +slack env set VERTEX_AI_PROJECT_ID +slack env set VERTEX_AI_LOCATION ``` The project location can be located under the **Region** on the [Vertex AI](https://console.cloud.google.com/vertex-ai) dashboard, as well as more details about available Gemini models. @@ -91,44 +91,16 @@ The project location can be located under the **Region** on the [Vertex AI](http -Unlock the OpenAI models from your OpenAI account dashboard by clicking [create a new secret key](https://platform.openai.com/api-keys), then export the key like so: +Unlock the OpenAI models from your OpenAI account dashboard by clicking [create a new secret key](https://platform.openai.com/api-keys), then set the key like so using the Slack CLI: ```bash -export OPENAI_API_KEY= +slack env set OPENAI_API_KEY ``` -## Setting up and running your local project {#configure-project} - - -Start your Python virtual environment: - - - - -```bash -python3 -m venv .venv -source .venv/bin/activate -``` - - - - -```bash -py -m venv .venv -.venv\Scripts\activate -``` - - - - -Install the required dependencies: - -```bash -pip install -r requirements.txt -``` +## Running your local project {#running-project} Run your app locally: diff --git a/docs/english/tutorial/custom-steps-for-jira/custom-steps-for-jira.md b/docs/english/tutorial/custom-steps-for-jira/custom-steps-for-jira.md index d74b82b8e..27709d0ad 100644 --- a/docs/english/tutorial/custom-steps-for-jira/custom-steps-for-jira.md +++ b/docs/english/tutorial/custom-steps-for-jira/custom-steps-for-jira.md @@ -76,7 +76,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - + ```bash python3 -m venv .venv diff --git a/docs/english/tutorial/order-confirmation/order-confirmation.md b/docs/english/tutorial/order-confirmation/order-confirmation.md index 695d6965a..27609e548 100644 --- a/docs/english/tutorial/order-confirmation/order-confirmation.md +++ b/docs/english/tutorial/order-confirmation/order-confirmation.md @@ -91,13 +91,18 @@ Still in the app settings, navigate to the **Install App** page in the left side Within a terminal of your choice, set the two tokens from the previous step as environment variables using the commands below. Make sure not to mix these two up, `SLACK_APP_TOKEN` will start with “xapp-“ and `SLACK_BOT_TOKEN` will start with “xoxb-“. -For macOS: + + + ```bash export SLACK_APP_TOKEN= export SLACK_BOT_TOKEN= ``` + + + For Windows Command Prompt: ```cmd @@ -112,9 +117,18 @@ $env:SLACK_APP_TOKEN="YOUR-APP-TOKEN-HERE" $env:SLACK_BOT_TOKEN="YOUR-BOT-TOKEN-HERE" ``` + + + ## Starting your app {#starting-your-app} -Run the following commands to activate a virtual environment for your Python packages to be installed, install the dependencies, and start your app. +If you're using the Slack CLI, you can start your local server with the following command: + +```bash +slack run +``` + +If you're not using the Slack CLI, you'll need to run the following commands to activate a virtual environment for your Python packages to be installed, install the dependencies, and then start your app. ```bash # Setup your python virtual environment @@ -125,12 +139,6 @@ source .venv/bin/activate pip install -r requirements.txt # Start your local server -slack run -``` - -If you're not using the Slack CLI, a different `python` command can be used to start your app instead: - -```sh python app.py ```