mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-13 04:16:48 +00:00
Slack Integration docs update (#26466)
* rework Setup section * remove note at top, update script, add note to create duplicates * text lint * Update slack.markdown * PR comments
This commit is contained in:
parent
a740a646b7
commit
a6b7965869
@ -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.
|
||||
|
||||
<div class='note'>
|
||||
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
|
||||
|
||||
</div>
|
||||

|
||||
|
||||
### 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 <https://google.com|this is a link>
|
||||
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.
|
||||
|
||||
<div class='note'>
|
||||
|
||||
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`.
|
||||
|
||||
</div>
|
||||
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 %}
|
||||
|
||||
|
BIN
source/images/integrations/slack/bot-token-scopes.png
Normal file
BIN
source/images/integrations/slack/bot-token-scopes.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 150 KiB |
BIN
source/images/integrations/slack/oauth-tokens-for-workspace.png
Normal file
BIN
source/images/integrations/slack/oauth-tokens-for-workspace.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 187 KiB |
BIN
source/images/integrations/slack/slack-integration-setup.png
Normal file
BIN
source/images/integrations/slack/slack-integration-setup.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 93 KiB |
BIN
source/images/integrations/slack/slack-message.png
Normal file
BIN
source/images/integrations/slack/slack-message.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 40 KiB |
Loading…
x
Reference in New Issue
Block a user