home-assistant.io/source/_integrations/slack.markdown

247 lines
7.7 KiB
Markdown

---
title: Slack
description: Instructions on how to add Slack notifications to Home Assistant.
ha_category:
- Notifications
ha_release: pre 0.7
ha_config_flow: true
ha_domain: slack
ha_iot_class: Cloud Push
ha_codeowners:
- '@bachya'
- '@tkdrob'
ha_platforms:
- notify
- sensor
ha_integration_type: service
---
The `slack` platform allows you to deliver notifications from Home Assistant to [Slack](https://slack.com/).
![](/images/integrations/slack/slack-message.png)
## Setup
### 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.
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
![](/images/integrations/slack/bot-token-scopes.png)
4. Scroll up to `OAuth Tokens & Redirect URLs` and click `Install to Workspace`.
In `Features/OAuth and Permissions/OAuth Tokens for Your Workspace`:
5. Copy the Bot User OAuth Token. Use this as 'API Key' when setting up in Home Assistant
![](/images/integrations/slack/oauth-tokens-for-workspace.png)
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.
#### 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
![](/images/integrations/slack/slack-integration-setup.png)
## 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://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 %}
One sensor entity will be created:
- **Do Not Disturb Timer**: The amount of time left for Do Not Disturb status.
### Slack Service Data
The following attributes can be placed inside the `data` key of the service call for extended functionality:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `username` | yes | The username of the Slack bot.
| `icon` | yes | The icon of the Slack bot.
| `file` | yes | A file to include with the message; see below.
| `blocks` | yes | Array of [Slack blocks](https://api.slack.com/messaging/composing/layouts). *NOTE*: if using `blocks`, they are shown **in place of** the `message` (note that the `message` is required nonetheless).
| `blocks_template` | yes | The same as `blocks`, but able to support [templates](https://www.home-assistant.io/docs/configuration/templating).
Note that using `file` will ignore all usage of `blocks` and `blocks_template` (as Slack does not support those frameworks in messages that accompany uploaded files).
To include a local file with the Slack message, use these attributes underneath the `file` key:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `path` | no | A local filepath that has been [whitelisted](/docs/configuration/basic/#allowlist_external_dirs).
To include a remote file with the Slack message, use these attributes underneath the `file` key:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `url` | no | A URL that has been [whitelisted](/docs/configuration/basic/#allowlist_external_urls).
| `username` | yes | An optional username if the URL is protected by HTTP Basic Auth.
| `password` | yes | An optional password if the URL is protected by HTTP Basic Auth.
### Examples
To send a file from local path:
```yaml
message: Message that will be added as a comment to the file.
title: Title of the file.
data:
file:
path: /path/to/file.ext
```
To send a file from remote path:
```yaml
message: Message that will be added as a comment to the file.
title: Title of the file.
data:
file:
url: "http://site.com/image.jpg"
```
To send a file from remote path that is protected by HTTP Basic Auth:
```yaml
message: Message that will be added as a comment to the file.
title: Title of the file.
data:
file:
url: "http://site.com/image.jpg"
username: user
password: pass
```
To use the block framework:
```yaml
message: Fallback message in case the blocks don't display anything.
title: Title of the file.
data:
blocks:
- type: section
text:
type: mrkdwn
text: 'Danny Torrence left the following review for your property:'
- type: section
block_id: section567
text:
type: mrkdwn
text: "<https://example.com|Overlook Hotel> \n :star: \n Doors had too many
axe holes, guest in room 237 was far too rowdy, whole place felt stuck in
the 1920s."
accessory:
type: image
image_url: https://is5-ssl.mzstatic.com/image/thumb/Purple3/v4/d3/72/5c/d3725c8f-c642-5d69-1904-aa36e4297885/source/256x256bb.jpg
alt_text: Haunted hotel image
- type: section
block_id: section789
fields:
- type: mrkdwn
text: |-
*Average Rating*
1.0
```
Send a message directly to a user by setting the target to their member ID. Here are [instructions](https://www.workast.com/help/articles/61000165203/) to obtain a member ID.
```yaml
message: "Hello there!"
target: "U12345"
title: "Hi"
data:
blocks: []
```
Send a message to a channel that mentions (@username, highlights a users name in yellow) a user. Here are [instructions](https://www.workast.com/help/articles/61000165203/) to obtain a member ID.
```yaml
message: "<@U12345> your appointment starts soon"
target: "#general"
title: "Reminder"
data:
blocks: []
```