Docs: guide quick start app creation using the slack cli. #1317
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
✅ All tests successful. No failed tests found. Additional details and impacted files@@ Coverage Diff @@
## main #1317 +/- ##
=======================================
Coverage 90.96% 90.96%
=======================================
Files 222 222
Lines 7501 7501
=======================================
Hits 6823 6823
Misses 678 678 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
@technically-tracy Wow! Thanks so much for putting this together so fast 🤖 ✨
I left a few comments on changes we'll need to make on the linked sample app and also some sample code we might want to include here!
These paths otherwise read well and some comments have thoughts on separating requirements more, but right now this makes most sense with the current capabilities released in the CLI ⚡
The comments on incoming CLI changes IMO don't have to block this from releasing either if we're alright with fast follows as well! 🚢 💨
|
|
||
| This page contains an overview of your app in addition to important credentials you'll need later. | ||
| A few tools are needed for the following steps. We recommend using the [**Slack CLI**](https://tools.slack.dev/slack-cli/) for the smoothest experience, but other options remain available. |
There was a problem hiding this comment.
📺 💾 We might also want to add an option of using git and the latest stable version of python?
|
|
||
| ### Create an app {#create-an-app} | ||
| First thing's first: before you start developing with Bolt, you'll want to [create a Slack app](https://api.slack.com/apps/new). | ||
| When complete, you'll have a local environment configured with a customized [app](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started) running to modify and make your own. |
There was a problem hiding this comment.
👾 The standalone "Getting Started App" repo might be alright to link here though I'm noticing a change is needed first:
manifest.json: To define the features of an app!
There was a problem hiding this comment.
🗣️ Changes to the sample app are in progress here: slack-samples/bolt-python-getting-started-app#3
|
|
||
| --- | ||
| After a project is created you'll have a `package.json` file for app dependencies and a `.slack` directory for Slack CLI configuration. |
There was a problem hiding this comment.
| After a project is created you'll have a `package.json` file for app dependencies and a `.slack` directory for Slack CLI configuration. | |
| After a project is created you'll have a `requirements.txt` file for app dependencies and a `.slack` directory for Slack CLI configuration. |
Right now this is unversioned which we might revisit soon with the kind help of @dependabot!
|
|
||
| ```shell | ||
| ```sh | ||
| which python3 | ||
| # Output: /path/to/first-bolt-app/.venv/bin/python3 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| Once the virtual environment is active, install the required project dependencies with the following command: | |
| ```sh | |
| pip install -r requirements.txt | |
| ``` |
IIRC some efforts are in progress to handle the creation and installation of packages in a virtual environment for the CLI track, but this command can be useful to include for now in both cases!
Polite tagging of @mwbrooks here for awareness 🙏 ✨
|
|
||
| <Tabs groupId="socket-or-http"> | ||
| <TabItem value="socket-mode" label="Socket Mode"> | ||
| Using an editor of choice, open the app.py file and add the following message listener after the "hello" handler: |
There was a problem hiding this comment.
| Using an editor of choice, open the app.py file and add the following message listener after the "hello" handler: | |
| Using an editor of choice, open the app.py file and add the following import to the top of the file, and message listener after the "hello" handler: | |
| ```python | |
| import random | |
| ``` |
This might not be the most clear organization, but TIL random is not a default package of Python! 🐍 ✨
| import os | ||
| from slack_bolt import App | ||
| from slack_bolt.adapter.socket_mode import SocketModeHandler | ||
| // SAMPLE CODE HERE |
There was a problem hiding this comment.
| // SAMPLE CODE HERE | |
| @app.message("goodbye") | |
| def message_goodbye(say): | |
| responses = ["Adios", "Au revoir", "Farewell"] | |
| parting = random.choice(responses) | |
| say(f"{parting}!") |
👋 Farewell or au revior or adios I cannot tell what this might output.
|
|
||
| We're going to use bot and app-level tokens for this guide. | ||
|
|
||
| 1. Navigate to the **OAuth & Permissions** on the left sidebar and scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. |
There was a problem hiding this comment.
| 1. Navigate to the **OAuth & Permissions** on the left sidebar and scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. | |
| 1. Navigate to **OAuth & Permissions** on the left sidebar and scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. |
There was a problem hiding this comment.
or "Navigate to the OAuth & Permissions page"
|
|
||
| The value inside of `say()` is now an object that contains an array of `blocks`. Blocks are the building components of a Slack message and can range from text to images to datepickers. In this case, your app will respond with a section block that includes a button as an accessory. Since we're using `blocks`, the `text` is a fallback for notifications and accessibility. | ||
|
|
||
| You'll notice in the button `accessory` object, there is an `action_id`. This will act as a unique identifier for the button so your app can specify what action it wants to respond to. |
There was a problem hiding this comment.
| You'll notice in the button `accessory` object, there is an `action_id`. This will act as a unique identifier for the button so your app can specify what action it wants to respond to. | |
| You'll notice in the button `accessory` object, there is an `action_id`. This will act as a unique identifier for the button so your app can specify which action it wants to respond to. |
|
|
||
| Now, if you restart your app and say "hello" in a channel your app is in, you'll see a message with a button. But if you click the button, nothing happens (_yet!_). | ||
|
|
||
| Let's add a handler to send a followup message when someone clicks the button: |
There was a problem hiding this comment.
| Let's add a handler to send a followup message when someone clicks the button: | |
| Let's add a handler to send a follow-up message when someone clicks the button: |
Summary
Docs: guide quick start app creation using the slack CLI following the Bolt for JS structure authored by @zimeg.
Testing
Category
slack_bolt.Appand/or its core componentsslack_bolt.async_app.AsyncAppand/or its core componentsslack_bolt.adapter/docsRequirements
Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.
./scripts/install_all_and_run_tests.shafter making the changes.