Node-RED Slack Bolt Integration

Control your Slack App via Node-Red! Slack Bolt integration.

What you can do with this node-red plugin?

• send simple text messages
• send complex block messages
• events: listen to any Slack Events
• actions: listen to user action and respond via Node-Red
• commands: create your own commands with your Slack App and listen via Node-Red
• shortcuts: create your own global or message based shortcuts and develop it with Node-Red
• views: Slack views
• messages: listing for messages in a channel

Develop your Slack app using Bolt for JavaScript with Node-Red.

npm i @headless-architecture/node-red-contrib-slack-bolt

Important

This is an alpha version, no grarranty for productive mode!

Usage

Setup Slack App

• open Slack App
• create new Slack App
• Choose from an app manifest
• Choose your workspace
• Copy from here or manifest below
• Paste into YAML section
• create app
• optional: If you need the app for events, then you will need a App-Level Token (see under Basic Information) select scope connection:write

Tip

Don't forget to install the app also into a channel.

Note

Could be that the installation of your slack app takes longer than 60min.

Slack Manifest

display_information:
  name: Node-Red-Integration
  description: Integrate Slack with Node-Red instance
  background_color: "#4f4e4b"
features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Node-Red-demo-app
    always_online: true
  shortcuts:
    - name: need_drink
      type: global
      callback_id: need_drink
      description: modal view for approve and deny
    - name: open_modal
      type: global
      callback_id: open_modal
      description: open simple modal
  slash_commands:
    - command: /node-red
      description: test
      should_escape: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - commands
      - reactions:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

Node-RED Installation

open your folder via favourite shell

npm i @headless-architecture/node-red-contrib-slack-bolt

Node-Red Configuration

After the installation of @headless-architecture/node-red-contrib-slack-bolt search in your Node-RED toolbar for slack

Nodes

• message: send text and block messages
• registry: registration of slack actions, events, commands, messages, options, shortcuts and views

Slack App Configuration

Name	Description
Bot Token required	communciation token (starts with xoxb-) see Slack App "OAuth/Permissions" -> "Bot User OAuth Token"
Log Level	Slack log levels more info
Socket	activate the socket mode, if you want to listen for changes in your channel. It is required for the registry nodes. see Slack App "Socked Mode"
Port	default is 3000 more info
App Token	Slack App Token (starts with xapp-) see slack app "Basic information" -> "App-level-Token" -> create new -> choose connections:write

Message

With this node, Node-RED is able to send direct messages into a channel. Private message to a person is not possible (yet).

Name	Description
Slack App	see Slack App Configuration above
Channel	slack channel, starts always with a hash (e.g. #main)
Property	variable of the content for a message
Topic	text or block message
Text	direct message (overwrite input stream)
Blocks	JSON format, complex messages with interactions (overwrite input stream)

Block Example

Simple Block for choosing a date

[
    {
        "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Pick a date for me to remind you"
        },
        "accessory": {
            "type": "datepicker",
            "action_id": "datepicker_remind",
            "initial_date": "2019-04-28",
            "placeholder": {
                "type": "plain_text",
                "text": "Select a date"
            }
        }
    }
]

• Block Kit Builder
• Formating Blocks

Registry

This node enable the following Slack functions.

• Actions
• Events
• Views
• Messages (listener, sending of messages see message node)
• Options
• Shortcuts
• Commands

Below of the node, you can verify the registrations of your events. A, E, V, M, O, S, C; Starting letter of the liste above.

All listener needs to add once. Therefor create a Infection with:


Connect a function node with the following code.

Magic Slack Code. This will listen for App mention in your channel.
e.g. Your App name @Node-Red-demo-app.

Write in your Slack channel: @Node-Red-demo-app What's up?

Slack will answer you with a button and if your press on the button the action will send an answer back.

// initialize your handlers. 
msg.SlackBolt = {
    actions: [],
    commands: [],
    events: [],
    shortcuts: [],
    options: [],
    messages: []
};

msg.SlackBolt.actions.push(
    {
        'id': 'button_click',
        'callback':
            async ({ body, ack, say }) => {
                // Acknowledge the action
                await ack();
                return await say(`<@${body.user.id}> clicked the button2x`);

            }
    }
);

msg.SlackBolt.events.push(
    {
        'id': 'app_mention',
        'callback':
            async ({ event, context, client, say }) => {
                try {
                    const response = await say({
                        blocks: [
                            {
                                type: 'section',
                                text: {
                                    type: 'mrkdwn',
                                    text: `Thanks for the mention <@${event.user}>! Here's a button`,
                                },
                                accessory: {
                                    type: 'button',
                                    text: {
                                        type: 'plain_text',
                                        text: 'Approve me',
                                        emoji: true,
                                    },
                                    value: 'button_click',
                                    action_id: 'button_click',
                                },
                            },
                        ],
                    });
                } catch (error) {
                    console.error(error);
                }
            }
    }
);

Node-Red Example

Import into your project. see Examples

https://flows.nodered.org/flow/368f36cbacfeba00b253086438f9a74d

Common Errors

Error: An API error occurred: channel_not_found
Solution: Your Slack App is not installed in the channel.

Error: An API error occurred: invalid_auth
Solution: Token are wrong.

Development

Installation

1. clone this repo git clone git@github.com:fishme/node-red-contrib-slack-bolt.git
2. This project is designed to work with yarn. If you don't have yarn installed, you can install it with npm install -g yarn.
3. Install dependencies: yarn install.

Dependencies

Node version >= 18.0.0

Developing Nodes

Link your project into your local Node-Red instance.

cd /path-to-node-red/.node-red
npm install ./path-to-this-project

Build & Test in Watch mode:

yarn dev

Building Node Set

Create a production build:

yarn build

Roadmap

Not or not full implementented

Knowing not critical Bugs

• Slack App: Fix Logging selection (not working)

Slack Features

Basic concepts

• Workflow

Advanced concepts

• Slack Error Handling
• Global Middleware
• Authorization
• Storage
• Middleware
• Customizing a receiver
• Custom HTTP routes:

Node Features

• automatic Jest tests
• typescript typings (remove any and unknown)
• add listener node (selection of listener mode and code block)

Documentation

• documentation page
• node documentation (improvment)
• code documentation
• Youtube tutorials (create slack app, configuration of slack bot by each listener)
• flow examples

Build

• replace rollup with webpack
• github action build (bring tests back)

Testing Node Set in Node-RED

Read Node-RED docs on how to install the node set into your Node-RED runtime.

Contact

Issues: https://github.com/fishme/node-red-contrib-slack-bolt/issues
Project Link: https://github.com/fishme/node-red-contrib-slack-bolt
Donate: Support the project

LinkedIn: Go in touch with me

License

MIT © David Hohl

Thank you

Alexk111 for providing the Node-Red Typescript starter.