diff --git a/source/_integrations/slack.markdown b/source/_integrations/slack.markdown
index b780dfcc72a..899b32b4d1a 100644
--- a/source/_integrations/slack.markdown
+++ b/source/_integrations/slack.markdown
@@ -18,39 +18,113 @@ ha_integration_type: service
The `slack` platform allows you to deliver notifications from Home Assistant to [Slack](https://slack.com/).
+
+
+
## Setup
-### Bot posting as you
+### Slack App
1. Create a [new app](https://api.slack.com/apps) under your Slack.com account.
2. Click the `OAuth & Permissions` link in the sidebar, under the Features heading.
-3. In the Scopes section, add the `chat:write` and `dnd:read` scopes and select `Send messages as user`. Many errors can occur if these options are not set correctly.
+
+Find `Features/OAuth and Permissions/Scopes/Bot Token Scopes`
+
+3. Add the `chat:write` and `dnd:read` scopes
+ - To modify your Slack bot's username and icon, additionally add the `chat:write.customize` OAuth scope
+
+
+
4. Scroll up to `OAuth Tokens & Redirect URLs` and click `Install to Workspace`.
-5. Copy your `OAuth Access Token` and put that key into the config flow.
-
+In `Features/OAuth and Permissions/OAuth Tokens for Your Workspace`:
-There is an app credential Verification Token on the Basic Settings of your app. This is **not** the API key you want.
+5. Copy the Bot User OAuth Token. Use this as 'API Key' when setting up in Home Assistant
-
+
-### Bot posting as its own user
-It is also possible to use Slack bots as users. Just create a new bot at https://[YOUR_TEAM].slack.com/apps/build/custom-integration and use the provided token for that. You can add an icon from the frontend for Home Assistant and give the bot a meaningful name.
+Ensure that the bot user is added to the channel in which you want it to post.
+In Slack, tag the bot user in a message, then add it to the channel.
-Don't forget to invite the bot to the room where you want to get the notifications.
+
+#### Sample App Manifest
+
+You can easily create a bot with all the permissions needed from an App Manifest.
+
+```yaml
+display_information:
+ name: Home Notifications
+features:
+ bot_user:
+ display_name: Home Notifications
+ always_online: false
+oauth_config:
+ scopes:
+ bot:
+ - incoming-webhook
+ - chat:write
+ - dnd:read
+ - chat:write.customize
+settings:
+ org_deploy_enabled: false
+ socket_mode_enabled: false
+ token_rotation_enabled: false
+```
+
+### Integration Setup
+
+When installing the integration, use these settings:
+
+API Key: `xoxb-abc-def`
+- Bot User OAuth Token (from step 5 above)
+
+Default Channel: `#channel`
+- Channel name that bot will post to if a channel is not supplied when called
+
+Icon/Username:
+- optional - if you want to have a custom name/icon for the bot user not already set in Slack
+
+
+
+## Usage
+
+### Sending Messages
+
+One of the easiest ways to send a message, is to create a script. You can paste in YAML and make changes in the GUI.
+
+You can call this script as a service.
+
+1. Go to Home Assistant Settings > Automations and Scenes > Scripts > Add Script
+2. Click the three dots in the top right, and pick 'Edit in YAML'. Paste in the contents below.
+3. Change `YOUR_SLACK_TEAM` to the team name `(*.slack.com)`
+
+```yaml
+alias: "Notify: Slack Notification Template"
+sequence:
+ - service: notify.YOUR_SLACK_TEAM
+ data:
+ message: Fallback Text
+ target: "#test-channel"
+ title: Reminder
+ data:
+ blocks:
+ - type: section
+ text:
+ type: mrkdwn
+ text: >-
+ This is a mrkdwn section block *this is bold*, and ~this is
+ crossed out~, and
+mode: single
+```
+
+Update the blocks array with valid Slack blocks. The easiest way to create this is using [Slack Block Kit Builder](https://app.slack.com/block-kit-builder)
+
+Create a duplicate of this script to use for different messages, and different channels (the door was opened in #security, the light was left on on #lights, etc).
### Icons
-Slack uses the standard emoji sets used [here](https://www.webpagefx.com/tools/emoji-cheat-sheet/). Alternatively a publicly accessible URL may be used.
-
-
-
-In order to modify your Slack bot's username and icon, you must ensure your Slack app has the `chat:write.customize` OAuth scope. See [the Slack API documentation](https://api.slack.com/methods/chat.postMessage#authorship) for more information.
-
-The added `notify` service will be named after the chat server the app is installed on. For example, a server named "Slack Chat" wil display as `notify.slack_chat`.
-
-
+Slack uses the standard emoji sets used [here](https://slack.com/intl/en-gb/help/articles/202931348-Use-emoji-and-reactions#add-emoji-to-your-messages). Alternatively a publicly accessible URL may be used.
{% include integrations/config_flow.md %}
diff --git a/source/images/integrations/slack/bot-token-scopes.png b/source/images/integrations/slack/bot-token-scopes.png
new file mode 100644
index 00000000000..b2a8db5351c
Binary files /dev/null and b/source/images/integrations/slack/bot-token-scopes.png differ
diff --git a/source/images/integrations/slack/oauth-tokens-for-workspace.png b/source/images/integrations/slack/oauth-tokens-for-workspace.png
new file mode 100644
index 00000000000..ad42b6f3234
Binary files /dev/null and b/source/images/integrations/slack/oauth-tokens-for-workspace.png differ
diff --git a/source/images/integrations/slack/slack-integration-setup.png b/source/images/integrations/slack/slack-integration-setup.png
new file mode 100644
index 00000000000..ec4bd0a4e45
Binary files /dev/null and b/source/images/integrations/slack/slack-integration-setup.png differ
diff --git a/source/images/integrations/slack/slack-message.png b/source/images/integrations/slack/slack-message.png
new file mode 100644
index 00000000000..50f3fea2e60
Binary files /dev/null and b/source/images/integrations/slack/slack-message.png differ