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.

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

[
    {
        "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 [email protected]: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.