#Slack

The Slack integration 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 following OAuth scopes:

• chat:write
• dnd:read
• channels:manage
• channels:read
• groups:read
• groups:write
• im:read
• im:write
• mpim:read
• mpim:write
• Optionally add chat:write.customize to modify your Slack bot's username and icon.

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

6. Ensure that the bot user is added to the channel in which you want it to post. This can be completed in several ways:

• Using /invite @bot from the channel
• Tagging the bot user in a message, then adding it to the channel via the Slackbot prompt.
• Channel settings -> Integrations -> Add apps

#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 an action.

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:
  - action: notify.YOUR_SLACK_TEAM
    data:
      message: "Fallback Text"
      target: "#test-channel" # Single channel target
      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>

Update the blocks array with valid Slack blocks. The easiest way to create this is using Slack Block Kit Builder. Up to 50 blocks may be included per message.

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).

You can also send messages to multiple targets (channels and/or users) at once:

alias: "Notify: Multiple Targets Message"
sequence:
  - action: notify.YOUR_SLACK_TEAM
    data:
      message: "Alert: Motion detected!"
      target: 
        - "#security"    # Channel by name
        - "C01234ABCD"   # Channel by ID
        - "U5678EFGH"    # Direct message to user by ID
      title: "Security Alert"
      data:
        blocks:
          - type: section
            text:
              type: mrkdwn
              text: "Motion detected in the backyard camera"

#Target Types

The target field accepts either a single value or a list of values. Each target can be:

• A channel name with a # prefix (e.g., #general)
• A channel name without the # prefix (e.g., general)
• A channel ID (e.g., C01234ABCD)
• A user ID for direct messages (e.g., U5678EFGH)

When sending files, make sure you have the proper permissions set up as described in the Setup section.

#Icons

Slack uses the standard emoji sets used here. Alternatively a publicly accessible URL may be used.

One sensor entity will be created:

• Do Not Disturb Timer: The amount of time left for Do Not Disturb status.

#Slack action data

The following attributes can be placed inside the data key of the action 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:

#Obtaining a member ID

Some of the examples below use a member ID. This is a unique string assigned by Slack to all users (members and guests) and not a username set by the user. To get a member ID:

1. Select a Slack user (both name and profile image work) to bring up their profile side panel.
2. Open the context menu by selecting the three dots.
3. Select Copy member ID.

#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 for notifications or 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.

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.

message: "<@MEMBER_ID> 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"