README
Slack Post
Node.js module for sending posts to Slack via the incoming webhooks API. Supports both simple and advanced messaging formats.
An existing incoming webhook integration will be required and can be created via the Slack administration system to successfully use this module.
For further API details see Incoming Webhooks and Message Attachments (advanced messaging) Slack API documents.
- Methods
- slackPost.post(webhookURL,postText)
- slackPost.setUsername(name)
- slackPost.setChannel(channel)
- slackPost.setIconEmoji(iconEmoji)
- slackPost.setIconURL(iconURL)
- slackPost.enableUnfurlLinks()
- slackPost.disableMarkdown()
- slackPost.setColor(color)
- slackPost.setPreText(preText[,enableMarkdown])
- slackPost.setAuthor(name[,authorURL][,iconURL])
- slackPost.setTitle(title[,URL])
- slackPost.setRichText(richText[,enableMarkdown])
- slackPost.addField(title,value[,isShort])
- slackPost.enableFieldMarkdown()
- slackPost.setThumbnail(URL)
- slackPost.setImage(URL)
- slackPost.setFooter(text[,timestamp][,iconURL])
- slackPost.send(callback)
- Example usage
Methods
slackPost.post(webhookURL,postText)
- Returns a new Slack Post message object instance.
webhookURL
must be in the format expected by the Slack administration integration endpoint - method will throw an error if web hook URL invalid.postText
is implemented as follows:- For simple messages (text posts) this will be the message text.
- For advanced messages will be used as the fall back text for scenarios where advanced rendering is unsupported.
Example:
var slackPost = require('slackpost');
var myNewPost = slackPost.post(
'https://hooks.slack.com/services/ABCDEF012/012345ABC/fjdke456HRekdftFOGRPh21s',
'Hello, HAL. Do you read me, HAL?'
);
slackPost.setUsername(name)
- Override default username for the incoming webhook.
- Returns
slackPost
object instance.
slackPost.setChannel(channel)
- Override default target channel for the incoming webhook with either:
- An alternative channel.
- Direct message Slack username.
- Format must be one of
#channel
or@username
, anything else will throw an error. - Returns
slackPost
object instance.
slackPost.setIconEmoji(iconEmoji)
- Override default icon for incoming webhook with a defined emoji.
- Provide desired emoji name without leading/trailing
:
characters. - Returns
slackPost
object instance.
Example:
var slackPost = require('slackpost');
var myNewPost = slackPost.post(WEBHOOK_URL,'Message');
// set the post icon to ":chicken:"
myNewPost.setIconEmoji('chicken');
slackPost.setIconURL(iconURL)
- Override the default icon for incoming webhook with a public image URL.
- Returns
slackPost
object instance.
slackPost.enableUnfurlLinks()
- When enabled, Slack will automatically attempt to extract and display summarized details for URLs within the post content.
- By default URLs referenced in posts made by an incoming webhook will not be unfurled - unless they are deemed media content links.
- Returns
slackPost
object instance.
slackPost.disableMarkdown()
- When disabled, Slack will avoid marking up post text with Markdown-like syntax.
- Method applies only to the simple message format, which by default is automatically marked up.
- Returns
slackPost
object instance.
slackPost.setColor(color)
- Sets left hand border color for advanced message format posts.
- Given
color
is either a HTML color code (e.g.#439fe0
) or one ofgood
,warning
ordanger
. - Color names are also defined at
require('slackpost').COLOR_LIST
. - If
color
isundefined
thenGOOD
will be used by default. - Returns
slackPost
object instance.
Example:
var slackPost = require('slackpost');
var myNewPost = slackPost.post(WEBHOOK_URL,'Message');
// color options
myNewPost.setColor(slackPost.COLOR_LIST['GOOD']);
myNewPost.setColor(slackPost.COLOR_LIST['WARNING']);
myNewPost.setColor(slackPost.COLOR_LIST['DANGER']);
myNewPost.setColor('#439fe0');
slackPost.setPreText(preText[,enableMarkdown])
- Set the optional text that appears above the advanced message block.
- If
enableMarkdown
is true, will action Slack Markdown-like formatting of givenpreText
. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.setAuthor(name[,authorURL][,iconURL])
- Sets a small display section at the top of the message for the post author.
- Optional
authorURL
allows setting of a URL for the author (will link both thename
andiconURL
within the rendered Slack post). - Optional
iconURL
will set a small 16x16px image to the left of the authorname
. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.setTitle(title[,URL])
- Sets a
title
, in bold text near the top of the message area. - Optional
URL
allows for the title to be hyperlinked. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.setRichText(richText[,enableMarkdown])
- Sets the
richText
(main text) for an advanced message post.- Content will automatically collapse if it contains 700+ characters or 5+ linebreaks, and will display a "Show more..." link to expand the content.
- If
enableMarkdown
is true, will action Slack Markdown-like formatting of givenrichText
. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.addField(title,value[,isShort])
- Adds message meta data in a tabular format at the footer of the message area. Method can be called multiple times to add multiple field items to the rendered table.
- Optional
isShort
boolean controls if field data is considered short enough to allow side-by-side tabular display with the following/next field item, otherwise fieldtitle
/value
will consume its own full table row. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
Example:
var slackPost = require('slackpost');
var myNewPost = slackPost.post(WEBHOOK_URL,'Message');
// add some fields - Name and Company will appear side-by-side
myNewPost.addField('Name','Don Draper',true);
myNewPost.addField('Company','Sterling Cooper',true);
// Job title field will appear on its own row
myNewPost.addField('Job title','Creative Director');
slackPost.enableFieldMarkdown()
- When called, will action Slack to markup field item values added via
slackPost.addField()
with Markdown-like syntax. - Method only applies to the advanced message format with one or more fields created.
- Returns
slackPost
object instance.
slackPost.setThumbnail(URL)
- Provides a public URL to an image that will be displayed as a thumbnail to the right of an advanced message.
- Image formats of GIF, JPEG, PNG and BMP are supported.
- When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.setImage(URL)
- Provides a public URL to an image that will be displayed as an image inside the message area.
- Image formats of GIF, JPEG, PNG and BMP are supported.
- Large images will be resized to a maximum width of 400px or a maximum height of 500px - whilst maintaining aspect ratio.
- When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.setFooter(text[,timestamp][,iconURL])
- Adds brief text to contextualize and identify referenced post content.
- Optional
timestamp
provided as a Unix timestamp will display a reference date/time to the right of the footer credit. - Optional
iconURL
will set a small 16x16px image to the left of the footertext
. - When called will enable the advanced message format.
- Returns
slackPost
object instance.
slackPost.send(callback)
- Sends a composed message, using the methods presented above to the Slack incoming webhook API endpoint.
callback
is expected to be a function, receiving one parameter:- Upon success parameter will be
null
. - In case of error, parameter will be an instance of
Error()
.
- Upon success parameter will be
Example usage
Sending a simple message:
var slackPost = require('slackpost');
var simpleMsg = slackPost.post(
'https://hooks.slack.com/services/ABCDEF012/012345ABC/fjdke456HRekdftFOGRPh21s',
'Hello, HAL. Do you read me, HAL?'
);
simpleMsg
.setUsername('HAL9000')
.setChannel('#spaceship')
.enableUnfurlLinks()
.disableMarkdown();
simpleMsg.send((err) => {
if (err) {
// error sending message to Slack API
console.dir(err);
return;
}
// success!
});
Sending an advanced message:
var slackPost = require('slackpost');
var advancedMsg = slackPost.post(
'https://hooks.slack.com/services/ABCDEF012/012345ABC/fjdke456HRekdftFOGRPh21s',
'This is my fallback text for mobile notifications and IRC users/etc.'
);
advancedMsg
.setUsername('magnetik')
.setChannel('@alexandra')
.setColor(slackPost.COLOR_LIST.WARNING)
.setAuthor(
'Peter Mescalchin',
'http://magnetikonline.com'
)
.setRichText('This is some *rich-text* messaging!',true);
advancedMsg.send((err) => {
if (err) {
// error sending message to Slack API
console.dir(err);
return;
}
// success!
});