nestjs-slack-bolt
v1.3.1
Published
A NestJS module for seamless integration with Slack using the Bolt SDK
Downloads
2,050
Maintainers
Readme
Table of Contents
- Description
- Features
- Installation
- Quick Start
- Configuration
- Usage
- Troubleshooting
- Changelog
- Contributing
- Support
- License
- Contributors
Description
This module provides a convenient way to develop Slack applications using the Nestjs framework. It seamlessly integrates the Slack Bolt SDK with NestJS, allowing you to leverage the power of both platforms.
Features
- Message Handling: Easily respond to and process incoming Slack messages.
- Command Handling: Implement custom Slack commands for your application.
- Action Handling: React to user interactions with buttons, select menus, and other Slack UI elements.
- Event Handling: Listen and respond to various Slack events in real-time.
- Shortcut Handling: Create and manage global and message shortcuts.
- View Submissions: Process and respond to modal view submissions.
- Seamless NestJS Integration: Utilize NestJS dependency injection and module system with Slack Bolt.
- Decorators for Easy Setup: Use custom decorators to quickly set up event listeners.
Installation
$ npm install nestjs-slack-bolt
# or
$ yarn add nestjs-slack-bolt
Quick Start
- Install the package
- Set up environment variables (see Configuration)
- Import SlackModule in your app.module.ts:
import { Module } from '@nestjs/common';
import { SlackModule } from 'nestjs-slack-bolt';
@Module({
imports: [SlackModule.forRoot()],
})
export class AppModule {}
- Use decorators in your controllers to handle Slack events
Configuration
Add these variables to your .env
file:
# Required for all modes
SLACK_BOT_TOKEN="xoxb-your-bot-token"
# Required for socket mode
SLACK_APP_TOKEN="xapp-your-app-token"
SLACK_SOCKET_MODE=true
# Required for HTTP mode
SLACK_SIGNING_SECRET="your-signing-secret"
You can also pass options to SlackModule.forRoot()
:
SlackModule.forRoot({
logLevel: LogLevel.DEBUG,
// other Bolt app options
});
Usage
Using annotations
Handling a message event
import { Controller } from '@nestjs/common';
import { Message } from 'nestjs-slack-bolt';
import { SlackEventMiddlewareArgs } from '@slack/bolt';
@Controller()
export class AppController {
@Message('hi')
message({ say }: SlackEventMiddlewareArgs) {
say('Hello, I received your message!');
}
// Other handlers...
}
Handling an action
import { Controller } from '@nestjs/common';
import { Action } from 'nestjs-slack-bolt';
import { SlackActionMiddlewareArgs } from '@slack/bolt';
@Controller()
export class AppController {
@Action('click')
action({ say }: SlackActionMiddlewareArgs) {
say('Click event received, nice job!');
}
// Other handlers...
}
Handling a command
import { Controller } from '@nestjs/common';
import { Command } from 'nestjs-slack-bolt';
import { SlackCommandMiddlewareArgs } from '@slack/bolt';
@Controller()
export class AppController {
@Command('/list')
command({ say }: SlackCommandMiddlewareArgs) {
say('The /list command has been received. Processing...');
}
// Other handlers...
}
Handling an event
import { Controller } from '@nestjs/common';
import { Event } from 'nestjs-slack-bolt';
import { SlackEventMiddlewareArgs } from '@slack/bolt';
@Controller()
export class AppController {
@Event('app_home_opened')
event({ say }: SlackEventMiddlewareArgs) {
say('The app was just opened!');
}
// Other handlers...
}
Handling a shortcut event
import { Controller } from '@nestjs/common';
import { Shortcut } from 'nestjs-slack-bolt';
@Controller()
export class AppController {
@Shortcut('test_shortcut')
async shortcut({ shortcut, ack, client, logger }) {
try {
await ack(); //Acknowledge shortcut request
const result = await client.views.open({
trigger_id: shortcut.trigger_id,
view: {
/* Your view parameters */
},
});
logger.info(result); // Log the result
} catch (error) {
logger.error(error); // Log any error
}
}
// Other handlers...
}
Using the SlackService
import { Controller } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { SlackService } from 'nestjs-slack-bolt/services/slack.service';
import { Cron, CronExpression } from '@nestjs/schedule';
import { from } from 'rxjs';
@Controller()
export class AppController {
constructor(
private readonly slackService: SlackService,
private readonly configService: ConfigService,
) {}
@Cron(CronExpression.EVERY_10_SECONDS)
cronJob() {
this.searchUsers()
.pipe()
.subscribe((users) => {
console.log(JSON.stringify(users));
});
}
searchUsers(cursor?: string) {
return from(
this.slackService.client.users.list({
token: this.configService.get('SLACK_BOT_TOKEN'),
limit: 1,
...(cursor && { cursor }),
}),
);
}
}
Troubleshooting
Here are some common issues and their solutions:
- "Cannot find module 'nestjs-slack-bolt'": Ensure you've installed the package correctly.
- "Invalid token": Double-check your SLACK_BOT_TOKEN in the .env file.
- Socket mode not working: Verify that SLACK_APP_TOKEN is set and SLACK_SOCKET_MODE is true.
For more issues, please check our GitHub issues or open a new one.
Changelog
See CHANGELOG.md for details on recent changes.
Contributing
We welcome contributions! Please see our CONTRIBUTING.md for details on how to contribute.
Support
For support, please open an issue on our GitHub repository.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification.