README
slack-utils
This is a collection of various slack-api related scripts that I've written. Published as an npm module.
Development is done in coffeescript, but that is not a dependency for usage.
Installation
npm install --save slack-utils
Usage
Currently, utils consists of 2 modules: api
and rtm
. All possible methods are demonstrated below:
// Initialize api
// You can leave either as undefined if you don't want to use those features
api = require('slack-utils/api')('SLACK_API_TOKEN', 'INCOMING_HOOK_URL')
// channel is the channel name (such as general)
// nick is the username of the user to send the message to
// username is the username used by the webhook
api.postMessage('message', 'channel', 'username')
// The icon can be set as final parameter in various ways (optional)
api.postMessage('message', 'channel', 'username', ":ghost:")
api.postMessage('message', 'channel', 'username', "ghost") // this is converted to an emoji
api.postMessage('message', 'channel', 'username', "https://www.gravatar.com/avatar/e") // A valid image url
// Sendmessage currently does not support icons
api.sendMessage('message', 'nick', 'username')
info = api.UserInfoById('U025QJXBB') //returns cached user info
info = api.UserInfoByName('nemo') //returns cached user info
// Initialize rtm
// You can get an API_TOKEN from https://api.slack.com/web for your personal account
// Or by creating a bot user at https://my.slack.com/services/new/bot
rtm = require('slack-utils/rtm')(API_TOKEN);
rtm.on('event', function(msg){
// Do whatever you want with the data
// msg.type will be same as event name
})
- A list of events emitted can be found at https://api.slack.com/rtm
- Few extra events are emitted as well:
connect
: When the websocket connects to the RTM serverready
: When Slack responds to our RTM connectionerror
: In case of an error in the websocket connectionactive
: When a user's presence changes to activeaway
: When a user's presence changes to away*
: Emitted for all slack-events (not for 3 low-level events: connect, ready, and error)
Differences
This is not a one-to-one mapping for the various slack APIs. This is done for a reason:
- Simplicity. You should be able to use various APIs without having to worry about things like userid translation
- Other 1-1 APIs already exist
- We add extra events and methods to simplify usage. For eg, we include a
sendMessage
and apostMessage
method to send a direct message or a public message. This is hidden inside the incoming webhook docs, but we surface it as 2 method calls. - The aim is to make your code more terse and readable.
Development
- Code is written in coffeescript
- Editorconfig is used for indentation guidelines
- Coffeescript is pushed to github
- Testing is done via mocha, and travis
npm test
works- Only javascript is pushed to npm
- Coffeescript is a development dependency, so its not installed in production
ws
andrequest
are used for websocket and http API usage- You will need to set an API token in environment to run tests
- You can put one in a
.env
file with the following contents:API_TOKEN=xoxb-4059276139-J54hTmEgjJGWa0FAKE_TOKEN
Help Needed
- Since I am pretty used to the slack API by now, I am very much comfortable writing this.
- I'd love if people used this for their services.
- Please file an issue if you have a usecase not covered by this.
- I am not used to writing javascript APIs, so I'd love to hear thoughts on how this can be improved
- Documentation. I'd get around to it soon, but I'd love a helping hand. Will probably use docco.
License
Licensed under MIT