node-red-contrib-slack

A Node-RED node to interact with
the Slack
API.

Install

Run the following command in the root directory of your Node-RED install:

``
npm install --save node-red-contrib-slack
`

Version 2.x of this package is NOT compatible with older versions. Plese
refer to the migration section for help.

Usage

The nodes included in this package are purposely generic in nature. The
usage very closely mimics the
Slack API. Your best source
of reference for input/output specifics will be from:

- https://api.slack.com
- https://api.slack.com/rtm
- https://api.slack.com/web
- https://api.slack.com/methods

4 nodes are provided:

- slack-rtm-in
- slack-rtm-out
- slack-web-out
- slack-state

The rtm API/node(s) are connected to slack via web sockets and are useful for
receiving a real-time stream of events/data.

The web API/node(s) are useful for making traditional web service calls and
have a much broader use-case.

Combining both rtm and web APIs provides a full solution to interact with
the Slack API in it's
entirety facilitating powerful flows in Node-RED. Which nodes are
appropriate to use for any given use-case can be subjective so familiarizing
youself with the documentation links above is extremely beneficial.

invoking methods

To invoke methods (slack-rtm-out,
slack-web-out) set the msg.topic to the name of the
method and set the msg.payload to the args/params.

The token property is NOT required to be set in any msg.payload.

As an example of invoking the
chat.meMessage
method with the slack-web-out node you would do the
following:

`
msg.topic = "chat.meMessage";
msg.payload = {
channel: "...",
text: "..."
}

return msg;
`

dressed output

The following nodes each provide
Slack API output:

- slack-rtm-in - view details of each event in the
documentation
- slack-rtm-out - view details of each event in the
documentation
- slack-web-out - view response section of each method in
the documentation

The respective events/responses are generally left unaltered and are directly
passed through as msg.payload. However, before outputting the msg the data
is traversed to enrich the msg.payload (examples provided below) with
complete object data where otherwise only internal Slack IDs are present.

All of the lookups are done dynamically/generically so regardless of what API
response you get if the node finds an attribute that appears to be a
supported object (user/channel/team/bot) in some shape or form, a
corresponding Object attribute with the lookup value will be
added.

For example, if the response contains a bot_id attribute you would see
bot_idObject added, or if it found an attribute called bot it would add
botObject etc. Ultimately all the lookups come from
slackState (see below) so it could be done on your own but
it's added to simplify and for convenience.

An example
user_typing
event from the slack-rtm-in node:

`
{
"type": "user_typing",
"channel": "...",
"user": "..."
}
`

is dressed to be sent as:

`
{
"type": "user_typing",
"channel": "...",
"user": "...",
"channelObject": {
"id": "...",
"name": "...",
"is_channel": true,
"is_group": false,
"is_im": false,
"created": 1434735155,
...
},
"userObject": {
"id": "...",
"name": "...",
"real_name": "...",
...
}
}
`

Helpers

As a convenience for both the slack-web-out and
slack-rtm-out nodes a special interface is supported that
allows you to send a message with a simplified structure (msg.topic starts
with @ or #):

`
msg.topic = "@some_user";


or

return msg
`

As an additional convenience, if you are invoking the
chat.meMessage,
chat.postEphemeral,
chat.postMessage
methods (slack-web-out), or
message method
(slack-rtm-out) and the channel starts with @ or #
the node will automatically lookup the appropriate channel.id from
slackState (see below) and set it for you.

slackState

All outputs for all nodes include a msg.slackState object which has several
properties containing the lists of members/channels/bots/team/etc so
downstream nodes can do 'lookups' without re-hitting the API (this data is
currently refreshed in the background every 10 minutes). Additionally the
internal state is connected to all relevant slack events and updates are
reflected real-time in any new messages (ie: a user getting created
automatically updates the slackState even before the 10 minute refresh).

nodes

$3

The slack-rtm-in node listens to
Slack RTM events and
outputs the dressed response as the msg.payload.

By default the node will listen to ALL events. You can however filter
event types by setting the node Slack Events property to a value
taking the form of type[::subtype][,type[::subtype],...]. For example
message to receive only events of type message or message::bot_message to
receive only events of type message which additionally have a subtype of
bot_message.

Example output:

`
{
"payload" {
"type": "user_typing",
"channel": "...",
"user": "...",
"channelObject": {
"id": "...",
"name": "...",
"is_channel": true,
"is_group": false,
"is_im": false,
"created": 1434735155,
...
},
"userObject": {
"id": "...",
"name": "...",
"real_name": "...",
...
}
},
"slackState": {
...
}
}
`

$3

Invokes a Slack RTM
method and outputs the dressed response as the
msg.payload.

Available methods:

- message: send a message
- ping: pong
- presence_sub:
to subscribe to
presence_change
events
- presence_query:
to request a one-time
presence_change
status
- typing: to send typing indicators

Using slack-rtm-out for sending messages should only be
used for very basic messages, preference would be to use the
chat.postMessage,
method of the slack-web-out node for anything beyond the
simplest messaging use-case as it supports
attachments
as well as many other features.

presence_sub
is a powerful slack-rtm-out method that allows you to
receive
presence_change
events on the slack-rtm-in node. See the
presence example below for further details.

Example input:

`
msg.topic = 'presence_query';
msg.payload = {
ids: [
'...'
]
}
return msg;
`

Example output:

`
{
"topic": "presence_query",
"payload": {
"ok":true,
"type":"presence_query"
},
"slackState": {
...
}
}
`

$3

Invokes a Slack Web
method and outputs the dressed response as the
msg.payload.

See the sending a message example for advanced message
sending.

Example input:

`
msg.topic = "chat.meMessage";
msg.payload = {
channel: "...",
text: "..."
}

return msg;
`

Example output:

`
{
"topic": "chat.meMessage",
"payload": {
"channel": "...",
"ts": "1552705036.049000",
"ok": true,
"scopes": [
"identify",
"read",
"post",
"client",
"apps"
],
"acceptedScopes": [
"chat:write:user",
"post"
],
"channelObject": {
"id": "...",
...
"userObject": {
"id": "...",
...
}
}
},
"slackState": {
...
}
}
`

$3

slack-state outputs a message with
msg.slackState added. If the msg.payload sent to
slack-state is true then it will first do a full refresh of
the state (should not generally be necessary) and then output the msg.

The state events (2nd) output of the node emits a signal when the state has
been fully initialized after (re)connect. This can be useful if you want to
perform any post initilization tasks (ie:
presence_sub
).

Example input:

`
msg.payload = true; // force a refresh
return msg;
`

Example output (state):

`
{
"slackState": {
...
}
}
`

Example output (state events):

`
{
"payload": {
"type":"ready"
},
"slackState": {
...
}
}
`

Examples / Advanced

sending a message

While you can send messages using the simplified syntax (msg.topic starts
with @ or # and msg.payload is the message) using either the
slack-web-out or the slack-rtm-out
nodes, your use-case may require more control. The most advanced message
sending can be accomplished by invoking the
chat.postMessage
method of the slack-web-out node:

`
var topic = "chat.postMessage";

var payload = {
// channel: "@someuser",
// or
// channel: "#somechannel",
text: "hi from bot",
...
// review linked documentation for all options
}

msg = {
topic: topic,
payload: payload
}

return msg;
`

respond to keyword

A simple respond to keyword example function node to place between a
slack-rtm-in node and a slack-web-out
node:

`
// ignore anything but messages
if (msg.payload.type != "message") {
return null;
}

// ignore deleted messages
if (msg.payload.subtype == "message_deleted") {
return null;
}

// ignore messages from bots
if (msg.payload.bot_id || (msg.payload.userObject && msg.payload.userObject.is_bot)) {
return null;
}

// if you only want to watch a specific channel put name here
var channel = "";
if (channel && !msg.payload.channelObject) {
return null;
}

if (channel && msg.payload.channelObject.name != channel.replace(/^@/, "").replace(/^#/, "")) {
return null;
}

// only specific users
var username = "";
if (username && !msq.payload.userObject) {
return null;
}

if (username && msq.payload.userObject.name.replace(/^@/, "") != username)) {
return null;
}

// check for keyword
// could use regex etc
if (!msg.payload.text.includes("keyword")) {
return null;
}

// prepare outbound response
var topic = "chat.postMessage";
var payload = {
channel: msg.payload.channel, // respond to same channel
//text: '<@' + msg.payload.userObject.name + '>, thanks for chatting',
text: '<@' + msg.payload.user + '>, thanks for chatting',
//as_user: false,
//username: "",
//attachments: [],
//icon_emoji: "",
}

msg = {
topic: topic,
payload: payload
}

return msg;
`

presence

While slackState does not automatically subscribe to
presence_change
events for you, it will keep track of presence details in
slackState if any
presence_change
events are received (this is all done behind the scenes).

To subscribe to
presence_change
events for all your users place the following function node between the
slack events output of the slack-state node and the
slack-rtm-out node:

`
msg.topic = 'presence_sub';
var ids = [];

for (var id in msg.slackState.members) {
if (msg.slackState.members.hasOwnProperty(id)) {
ids.push(id)
}
}

msg.payload = {
ids: ids
}
return msg;
`

The theory of operation is:

1. wait for the slackState to be initialized so you have a
complete list of members
1. iterate that list to build up the appropriate request to
slack-rtm-out
1. subscribe to presence events by sending the message to
slack-rtm-out
1. receive presence events on the slack-rtm-in node

Immediately after the request is sent you will see a flood of
presence_change
events emitted on the slack-rtm-in node. Once the initial
flood of messages has passed continued updates will come through as
appropriate. Again, behind the scenes the slack-state nodes
are listening for these events and updating the
slackState.presence values appropriately for general
usage/consumption in your flow(s).

If you are really interested in keeping the data updated you could capture
team_join events from a slack-rtm-in node and wire those
to the above function node as well triggering the same procedure when new
users join the team. You may need to put a delay node before the
function node just to give slackState enough time to process
this same event and update.

An alternative would be to wire an inject node to the function node and put
it on a sane interval such as every 10 minutes.

If you wanted to be really sure you are receiving all
presence_change
events for the whole team do all the above.

migration from 0.1.2 or earlier

In order to replicate the previous behavior it is possible to introduce simple
function nodes.

Roughly speaking the node equivalents are:

| 0.1.2 | 2.x |
| --------------------------------- | --------------------------------- |
| slack | slack-web-out |
| Slack Bot In | slack-rtm-in |
| Slack Bot Out | slack-rtm-out |

slack

To replicate the slack node simply place the following function node just
before the new slack-web-out node:

`
// https://api.slack.com/methods/chat.postMessage
msg.topic = "chat.postMessage"
var payload = {
text: msg.payload
};

// set default username (replicate the node configuration value)
var username = "";
if (username) {
payload.username = username;
payload.as_user = false;
} else if (msg.username) {
payload.username = msg.username;
payload.as_user = false;
}

// set default emojiIcon (replicate the node configuration value)
var emojiIcon = "";
if (emojiIcon) {
payload.icon_emoji = emojiIcon;
} else if (msg.emojiIcon) {
payload.icon_emoji = msg.emojiIcon;
}

// set default channel (replicate the node configuration value)
var channel = "";
if (channel) {
payload.channel = channel;
} else if (msg.channel) {
payload.channel = msg.channel
}

if (msg.attachments) {
payload.attachments = msg.attachments;
}

msg.payload = payload;

return msg;
`

Slack Bot In

To replicate the Slack Bot In node simply place the following function node
downstream from the new slack-rtm-in node:

`
// https://api.slack.com/events/message

if (msg.payload.type != "message") {
return null;
}

// if you only want to watch a specific channel put name here
var channel = "";
if (channel && !msg.payload.channelObject) {
return null;
}

if (channel && msg.payload.channelObject.name != channel.replace(/^@/, "").replace(/^#/, "")) {
return null;
}

var payload = "";
if (msg.payload.text) {
payload += msg.payload.text;
}

if (msg.payload.attachments) {
if (payload) {
payload += "\n";
}

msg.payload.attachments.forEach((attachment, index) => {
if (index > 0) {
payload += "\n";
}
payload += attachment.fallback;
})
}

var slackObj = {
id: msg.payload.client_msg_id,
type: msg.payload.type,
text: msg.payload.text,
channelName: msg.payload.channelObject.name,
channel: msg.payload.channelObject,
fromUser: (msg.payload.userObject) ? msg.payload.userObject.name : "",
attachments: msg.payload.attachments
};

msg = {
payload: payload,
slackObj: slackObj
}

return msg;
`

Slack Bot Out

To replicate the Slack Bot Out node simply place the following function
node just before the new slack-rtm-out node:

`
// set channel
var channel = "";
if (channel) {
// do nothing, use the provided channel
} else if (msg.channel) {
channel = msg.channel;
} else if (msg.slackObj && msg.slackObj.channel) {
channel = msg.slackObj.channel
} else {
node.error("'slackChannel' is not defined, check you are specifying a channel in the message (msg.channel) or the node config.");
node.error("Message: '" + JSON.stringify(msg));
return null;
}

msg = {
topic: channel,
payload: msg.payload
}

return msg;
``

Additional Resources

- Emoji Cheat Sheet
- Slack Attachments
- https://slack.dev/node-slack-sdk/
- https://slack.dev/node-slack-sdk/rtm_api
- https://slack.dev/node-slack-sdk/web_api