Repository navigation
Update Getting Started Guide to use Socket Mode - #405
Conversation
Codecov Report
@@ Coverage Diff @@
## main #405 +/- ##
=======================================
Coverage 91.36% 91.36%
=======================================
Files 167 167
Lines 5491 5491
=======================================
Hits 5017 5017
Misses 474 474 Continue to review full report at Codecov.
|
| ```python | ||
| import os | ||
| from slack_bolt import App | ||
| from slack_bolt.adapter.socket_mode import SocketModeHandler |
There was a problem hiding this comment.
# signing_secret=os.environ.get("SLACK_SIGNING_SECRET") # not required for socket mode
We can do the same for this code snippet
| There are three main token types available to a Slack app: user (`xoxp`), bot (`xoxb`), and app-level (`xapp`) tokens. | ||
| - [User tokens](https://api.slack.com/authentication/token-types#user) allow you to call API methods on behalf of users after they install or authenticate the app. There may be several user tokens for a single workspace. | ||
| - [Bot tokens](https://api.slack.com/authentication/token-types#bot) are associated with bot users, and are only granted once in a workspace where someone installs the app. The bot token your app uses will be the same no matter which user performed the installation. Bot tokens are the token type that _most_ apps use. | ||
| - [App-level tokens](https://api.slack.com/authentication/token-types#app) represent your app across organizations, including installations by all individual users on all workspaces in a given organization and are commonly used for creating websocket connections to your app. |
There was a problem hiding this comment.
nit: we may want to apply the same change to bolt-js document.
| - [App-level tokens](https://api.slack.com/authentication/token-types#app) represent your app across organizations, including installations by all individual users on all workspaces in a given organization and are commonly used for creating websocket connections to your app. | |
| - [App-level tokens](https://api.slack.com/authentication/token-types#app) represent your app across organizations, including installations by all individual users on all workspaces in a given organization and are commonly used for creating WebSocket connections to your app. |
|
|
||
| When you're finished, you'll have this ⚡️[Getting Started with Slack app](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started) to run, modify, and make your own. | ||
|
|
||
| > 💡 For this guide, we are going to be using [Socket Mode](https://api.slack.com/apis/connections/socket), our recommended option for those just getting started and building something for their team. If you already know you're going to want to use HTTP as your app's communication protocol, head over to our parallel guide, [Getting Started over HTTP](/bolt-python/tutorial/getting-started-http). |
There was a problem hiding this comment.
If we have this notice at the top of the page (I know we have the section in the middle in the bolt-js one), we may want to skip the steps to set SLACK_SIGNING_SECRET env variable and spin up a web server with 3000 port. With this, developers can directly turn Socket Mode on right after new app creation. Thoughts?
There was a problem hiding this comment.
@seratch Yeah, with this notice at the top, I think it's fair to say that it then becomes a little more misleading when we do initial setup with SLACK_SIGNING_SECRET
- Option 1: We keep this disclaimer at the top, and then we include the app-level-token setup along with the xoxb token setup.
- Option 2: We move the disclaimer to the middle (in "Setting up events") as it is in the bolt-js guide and then keep the
SLACK_SIGNING_SECRETsteps.
Option 1 is potentially less misleading, but one possible downside is there's a bit more concepts to introduce before devs can even start the app.
Any strong preference?
There was a problem hiding this comment.
My preference is option 1 as it's much simpler and easier for many. That being said, it's not a so much strong opinion. Either way, bolt-js and bolt-python should be consistent here (I don't say bolt-java should be the same too as it has been a bit different from the beginning).
There was a problem hiding this comment.
Thanks for that feedback @seratch !
I've pushed up some changes in line with taking Option 1. It's simpler to follow since all setup steps are now in the same section ( i.e. getting xapp is now in the same section as xoxb and toggling on Socket Mode) so there'll be less switching around from code to app config for the dev. And, omitting the signing secret part from code samples means we avoid introducing a confusing concept that's not useful ultimately unless you want to use Request URL.
Since there's now a note at the top and in the middle AND the bottom with links to get to the standalone guide for Getting Started with HTTP, I'm satisfied there's ample departure points for people with context on why they might want to switch. Let me know what you think!
There was a problem hiding this comment.
@srajiang I also like the revised version a lot! Great work 👍
Since there's now a note at the top and in the middle AND the bottom with links to get to the standalone guide for Getting Started with HTTP, I'm satisfied there's ample departure points for people with context on why they might want to switch. Let me know what you think!
When I read it as a whole, I felt the same! I'm sure that the current version does not have any confusing part for both Socket Mode users and HTTP mode users.
|
When merging this pull request, you can use "Squash and merge" to easily squash the commits! |
2 participants
In line with changes introduced to Bolt for JS in #990, this PR updates the Getting Started guide to use Socket Mode as default, and links a separate Getting Started over HTTP guide with instructions for Request URL / HTTP setup.
Category (place an
xin each of the[ ])slack_bolt.Appand/or its core componentsslack_bolt.async_app.AsyncAppand/or its core componentsslack_bolt.adapter/docsRequirements (place an
xin each[ ])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.