Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mishk0/slack-bot-api
:rocket: Simple way to control your Slack Bot
https://github.com/mishk0/slack-bot-api
Last synced: about 20 hours ago
JSON representation
:rocket: Simple way to control your Slack Bot
- Host: GitHub
- URL: https://github.com/mishk0/slack-bot-api
- Owner: mishk0
- License: mit
- Created: 2015-05-30T13:41:55.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T23:50:36.000Z (about 2 years ago)
- Last Synced: 2024-12-31T06:03:40.781Z (12 days ago)
- Language: JavaScript
- Homepage:
- Size: 240 KB
- Stars: 1,347
- Watchers: 23
- Forks: 176
- Open Issues: 76
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- Starred-Repo - Slack Bot API
README
# SlackBots.js
[](https://raw.githubusercontent.com/mishk0/slack-bot-api/master/LICENSE)
[](https://travis-ci.org/mishk0/slack-bot-api)
[](https://www.npmjs.com/package/slackbots)
This is Node.js library for easy operation with Slack API.
It also exposes all opportunities of Slack's Real Time Messaging API.
## Installation
```
npm install slackbots
```
### Params
- `token` (string) the slack token
- `name` (string) the name of the bot
- `disconnect` (boolean, defaults: `false`) whether to open websocket connection to listen to incoming messages, set to `true` for one time use
### Events
- `start` - event fired, when Real Time Messaging API is started (via websocket),
- `message` - event fired, when something happens in Slack. Description of all events here,
- `open` - websocket connection is open and ready to communicate,
- `close` - websocket connection is closed.
- `error` - an error occurred while connecting to Slack
### Methods
- `getChannels()` (return: promise) - returns a list of all channels in the team,
- `getGroups()` (return: promise) - returns a list of all groups in the team,
- `getUsers()` (return: promise) - returns a list of all users in the team,
- `getImChannels()` (return: promise) - returns a list of bots direct message channels in the team,
- `getChannel(name)` (return: promise) - gets channel by name,
- `getGroup(name)` (return: promise) - gets group by name,
- `getUser(name)` (return: promise) - gets user by name,
- `getUserByEmail(name)` (return: promise) - gets user by name,
- `getChannelId(name)` (return: promise) - gets channel ID by name,
- `getGroupId(name)` (return: promise) - gets group ID by name,
- `getUserId(name)` (return: promise) - gets user ID by name,
- `getChatId(name)` (return: promise) - it returns or opens and returns a direct message channel ID,
- `postEphemeral(id, user, text, params)` (return: promise) - posts an ephemeral message to channel and user by ID,
- `postMessage(id, text, params)` (return: promise) - posts a message to channel | group | user by ID,
- `updateMessage(channelId, timestamp, text, params)` (return: promise) - updates a message in a channel,
- `postTo(name, message [, params, callback])` (return: promise) - posts a message to channel | group | user by name,
- `postMessageToUser(name, message [, params, callback])` (return: promise) - posts a direct message by user name,
- `postMessageToGroup(name, message [, params, callback])` (return: promise) - posts a message to private group by name,
- `postMessageToChannel(name, message [, params, callback])` (return: promise) - posts a message to channel by name.
- `openIm(userId)` (return: promise) - opens a direct message channel with another member in the team
## Usage
```js
var SlackBot = require('slackbots');
// create a bot
var bot = new SlackBot({
token: 'xoxb-012345678-ABC1DFG2HIJ3', // Add a bot https://my.slack.com/services/new/bot and put the token
name: 'My Bot'
});
bot.on('start', function() {
// more information about additional params https://api.slack.com/methods/chat.postMessage
var params = {
icon_emoji: ':cat:'
};
// define channel, where bot exist. You can adjust it there https://my.slack.com/services
bot.postMessageToChannel('general', 'meow!', params);
// define existing username instead of 'user_name'
bot.postMessageToUser('user_name', 'meow!', params);
// If you add a 'slackbot' property,
// you will post to another user's slackbot channel instead of a direct message
bot.postMessageToUser('user_name', 'meow!', { 'slackbot': true, icon_emoji: ':cat:' });
// define private group instead of 'private_group', where bot exist
bot.postMessageToGroup('private_group', 'meow!', params);
});
```
PROFIT!
```js
/**
* @param {object} data
*/
bot.on('message', function(data) {
// all ingoing events https://api.slack.com/rtm
console.log(data);
});
```
### Response Handler
The simplest way for handling response is callback function, which is specified as a last argument:
```js
bot.postMessageToUser('user1', 'hi', function(data) {/* ... */});
bot.postMessageToUser('user1', 'hi', params, function(data) {/* ... */});
```
But also you can use promises.
Error:
```js
bot.postMessageToUser('user1', 'hi').fail(function(data) {
//data = { ok: false, error: 'user_not_found' }
})
```
Success:
```js
bot.postMessageToUser('user', 'hi').then(function(data) {
// ...
})
```
Error and Success:
```js
bot.postMessageToUser('user', 'hi').always(function(data) {
// ...
})
```