Slack

The slack platform allows you to deliver notifications from Home Assistant to Slack.

Setup

Slack App

1. Create a new app 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

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

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.

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)

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

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. Alternatively a publicly accessible URL may be used.

Configuration

To add the Slack integration to your Home Assistant instance, use this My button:

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:

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:

To include a remote file with the Slack message, use these attributes underneath the file key:

Examples

To send a file from local path:

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:

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:

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:

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 to obtain a member ID.

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 to obtain a member ID.

message: "<@U12345> your appointment starts soon"
target: "#general"
title: "Reminder"
data:
  blocks: []

Send a message as reply to an existing message. thread_ts can be retrieved via a script utilising Bolt, any other Slack library, or the Slack API directly.

message: "Here's some supplementary information that doesn't need to be present in the channel directly."
target: "#general"
data:
  thread_ts: "1684736481.064129"